filingstudio 0.4.0__py3-none-any.whl

filingstudio/__init__.py

@@ -0,0 +1,48 @@
+"""Filing Studio client: search SEC filings, resolve traces, verify claims."""
+
+from . import research
+from .client import AsyncFilingStudio, FilingStudio
+from .errors import FilingStudioError, NotConfigured, RateLimitError
+from .models import (
+    ContextRow,
+    CoverageResult,
+    EvidenceLinks,
+    EvidenceSource,
+    FilingRef,
+    FilingsResult,
+    IndexState,
+    Pagination,
+    SearchCell,
+    SearchPassage,
+    SearchResult,
+    TableResult,
+    TraceDetail,
+    VerifyReceipt,
+    VerifyResult,
+)
+
+__version__ = "0.4.0"
+__all__ = [
+    "AsyncFilingStudio",
+    "ContextRow",
+    "CoverageResult",
+    "EvidenceLinks",
+    "EvidenceSource",
+    "FilingRef",
+    "FilingStudio",
+    "FilingStudioError",
+    "FilingsResult",
+    "IndexState",
+    "NotConfigured",
+    "Pagination",
+    "RateLimitError",
+    "SearchCell",
+    "SearchPassage",
+    "SearchResult",
+    "TableResult",
+    "TraceDetail",
+    "VerifyReceipt",
+    "VerifyResult",
+    "__version__",
+    "research",
+]

filingstudio/client.py

@@ -0,0 +1,333 @@
+"""
+The Filing Studio client, sync and async. One method per /v1 door, the same
+names as the Node `@filingstudio/client` and the browser `ProvenanceClient`.
+
+    from filingstudio import FilingStudio
+    fs = FilingStudio(api_key=os.environ["FILING_STUDIO_API_KEY"])
+    hits = fs.search("NVDA", "purchase commitments", type="prose")
+    v = fs.verify("NVDA", metric="Revenue", value=130497, period="FY2025")
+
+The key travels only in the X-API-Key header, never in a URL, never in an
+error message. 5xx and transport failures are retried with backoff; 4xx are
+not. Pass `value` to verify as the raw figure you hold: the API tries every
+printed scale a filer could use.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+import anyio
+import httpx
+
+from .errors import FilingStudioError, NotConfigured, RateLimitError
+from .models import (
+    CoverageResult,
+    FilingsResult,
+    IndexState,
+    SearchResult,
+    TableResult,
+    TraceDetail,
+    VerifyResult,
+    parse_hit,
+)
+
+DEFAULT_BASE = "https://api.filingstudio.com"
+
+
+def _clean(params: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None and v != ""}
+
+
+def _describe(status: int, body: Any) -> "tuple[str, Optional[str]]":
+    err = body.get("error") if isinstance(body, dict) else None
+    if isinstance(err, str):
+        return err, None
+    if isinstance(err, dict):
+        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
+    return f"HTTP {status}", None
+
+
+def _raise_for(status: int, body: Any) -> None:
+    """Map a non-2xx answer to an exception. Never touches the key."""
+    if status == 429:
+        st = body.get("indexState") if isinstance(body, dict) else None
+        index_state = IndexState.model_validate(st) if isinstance(st, dict) else IndexState(
+            coverage="unavailable", note=_describe(429, body)[0]
+        )
+        raise RateLimitError(index_state, body)
+    msg, code = _describe(status, body)
+    raise FilingStudioError(status, msg, code, body)
+
+
+class _Base:
+    def __init__(
+        self,
+        api_key: Optional[str],
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        key = (api_key or "").strip()
+        if not key:
+            raise NotConfigured()
+        self._key = key
+        self._base = (base_url or DEFAULT_BASE).rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max(0, int(max_retries))
+
+    def _headers(self, json_body: bool) -> Dict[str, str]:
+        h = {"X-API-Key": self._key, "Accept": "application/json"}
+        if json_body:
+            h["Content-Type"] = "application/json"
+        return h
+
+    def _url(self, path: str) -> str:
+        return f"{self._base}{path}"
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        return 0.2 * (2 ** (attempt - 1)) + random.random() * 0.1
+
+    @staticmethod
+    def _parse(res: httpx.Response) -> Any:
+        try:
+            return res.json()
+        except ValueError:
+            return None
+
+    @staticmethod
+    def _unreachable(exc: Optional[BaseException]) -> FilingStudioError:
+        reason = type(exc).__name__ if exc else "network error"
+        return FilingStudioError(0, f"Filing Studio could not be reached ({reason}).", "unreachable")
+
+    # ---- result shaping, shared by sync and async ---------------------------
+
+    @staticmethod
+    def _search(body: Any, default_type: str) -> SearchResult:
+        env = body if isinstance(body, dict) else {}
+        data = env.get("data") or {}
+        return SearchResult(
+            type=data.get("type") or default_type,
+            results=[parse_hit(h) for h in (data.get("results") or [])],
+            indexState=env.get("indexState") or {},
+            pagination=env.get("pagination"),
+            note=env.get("note"),
+        )
+
+    @staticmethod
+    def _verify(body: Any) -> VerifyResult:
+        env = body if isinstance(body, dict) else {}
+        data = dict(env.get("data") or {})
+        data["indexState"] = env.get("indexState") or {}
+        return VerifyResult.model_validate(data)
+
+    @staticmethod
+    def _trace(body: Any) -> Optional[TraceDetail]:
+        env = body if isinstance(body, dict) else {}
+        traces = (env.get("data") or {}).get("traces") or []
+        return TraceDetail.model_validate(traces[0]) if traces else None
+
+    @staticmethod
+    def _filings(body: Any, ticker: str) -> FilingsResult:
+        env = body if isinstance(body, dict) else {}
+        data = env.get("data") or {}
+        return FilingsResult(
+            ticker=data.get("ticker") or ticker,
+            filings=data.get("filings") or [],
+            indexState=env.get("indexState") or {},
+            pagination=env.get("pagination"),
+            note=env.get("note"),
+        )
+
+    @staticmethod
+    def _coverage(body: Any, ticker: str) -> CoverageResult:
+        env = body if isinstance(body, dict) else {}
+        data = dict(env.get("data") or {})
+        data.setdefault("ticker", ticker)
+        data["note"] = env.get("note")
+        return CoverageResult.model_validate(data)
+
+    @staticmethod
+    def _table(body: Any) -> TableResult:
+        env = body if isinstance(body, dict) else {}
+        return TableResult(
+            data=env.get("data") or {},
+            provenance=env.get("provenance") or {},
+            links=env.get("links") or {},
+        )
+
+    # ---- paths ----------------------------------------------------------------
+
+    @staticmethod
+    def _search_params(ticker, q, type, period, forms, limit, offset) -> Dict[str, Any]:
+        return _clean({"ticker": ticker.upper(), "q": q, "type": type, "period": period,
+                       "forms": forms, "limit": limit, "offset": offset})
+
+    @staticmethod
+    def _trace_path(trace_id: str, include_context: bool) -> str:
+        return f"/v1/trace/{quote(trace_id, safe='')}" + ("?include=context" if include_context else "")
+
+    @staticmethod
+    def _table_path(ticker: str, accession: str, table_id: str) -> str:
+        return (f"/v1/tables/{quote(ticker.upper(), safe='')}/{quote(accession, safe='')}/"
+                f"{quote(table_id, safe='')}")
+
+
+class FilingStudio(_Base):
+    """Synchronous client. Use as a context manager to reuse one connection."""
+
+    def __init__(self, api_key: Optional[str], *, base_url: Optional[str] = None,
+                 timeout: float = 30.0, max_retries: int = 2,
+                 transport: Optional[httpx.BaseTransport] = None) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries)
+        self._http = httpx.Client(timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "FilingStudio":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+                 json: Any = None) -> Any:
+        last: Optional[BaseException] = None
+        for attempt in range(self._max_retries + 1):
+            if attempt:
+                time.sleep(self._backoff(attempt))
+            try:
+                res = self._http.request(method, self._url(path), params=params, json=json,
+                                         headers=self._headers(json is not None))
+            except httpx.TransportError as exc:
+                last = exc
+                continue
+            body = self._parse(res)
+            if res.is_success:
+                return body if body is not None else {}
+            if res.status_code >= 500:
+                last = FilingStudioError(res.status_code, _describe(res.status_code, body)[0], None, body)
+                continue
+            _raise_for(res.status_code, body)
+        if isinstance(last, FilingStudioError):
+            raise last
+        raise self._unreachable(last)
+
+    def search(self, ticker: str, q: str, *, type: Optional[str] = None, period: Optional[str] = None,
+               forms: Optional[str] = None, limit: Optional[int] = None,
+               offset: Optional[int] = None) -> SearchResult:
+        """Search a company's printed rows, tables, and prose by plain words."""
+        body = self._request("GET", "/v1/search",
+                             params=self._search_params(ticker, q, type, period, forms, limit, offset))
+        return self._search(body, type or "all")
+
+    def verify(self, ticker: str, *, metric: Optional[str] = None, value: Optional[float] = None,
+               period: Optional[str] = None, claim: Optional[str] = None) -> VerifyResult:
+        """Check a claim against what the filings print. Deterministic."""
+        payload = _clean({"ticker": ticker.upper(), "metric": metric, "value": value,
+                          "period": period, "claim": claim})
+        return self._verify(self._request("POST", "/v1/verify", json=payload))
+
+    def trace(self, trace_id: str, *, include_context: bool = True) -> Optional[TraceDetail]:
+        """Resolve a traceId to the exact printed line, with neighbouring rows."""
+        return self._trace(self._request("GET", self._trace_path(trace_id, include_context)))
+
+    def filings(self, ticker: str, *, form: Optional[str] = None, year: Optional[str] = None,
+                limit: Optional[int] = None) -> FilingsResult:
+        """A company's indexed filings."""
+        t = ticker.upper()
+        body = self._request("GET", f"/v1/filings/{quote(t, safe='')}",
+                             params=_clean({"form": form, "year": year, "limit": limit}))
+        return self._filings(body, t)
+
+    def coverage(self, ticker: str) -> CoverageResult:
+        """Is there anything indexed for this ticker, and how fresh?"""
+        t = ticker.upper()
+        return self._coverage(self._request("GET", "/v1/coverage", params={"ticker": t}), t)
+
+    def table(self, ticker: str, accession: str, table_id: str, *, format: str = "records") -> TableResult:
+        """One printed table, as filed: heading, row order, period headers, traces."""
+        return self._table(self._request("GET", self._table_path(ticker, accession, table_id),
+                                         params={"format": format}))
+
+
+class AsyncFilingStudio(_Base):
+    """Asynchronous client with the same methods."""
+
+    def __init__(self, api_key: Optional[str], *, base_url: Optional[str] = None,
+                 timeout: float = 30.0, max_retries: int = 2,
+                 transport: Optional[httpx.AsyncBaseTransport] = None) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries)
+        self._http = httpx.AsyncClient(timeout=timeout, transport=transport)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncFilingStudio":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def _request(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+                       json: Any = None) -> Any:
+        last: Optional[BaseException] = None
+        for attempt in range(self._max_retries + 1):
+            if attempt:
+                await anyio.sleep(self._backoff(attempt))
+            try:
+                res = await self._http.request(method, self._url(path), params=params, json=json,
+                                               headers=self._headers(json is not None))
+            except httpx.TransportError as exc:
+                last = exc
+                continue
+            body = self._parse(res)
+            if res.is_success:
+                return body if body is not None else {}
+            if res.status_code >= 500:
+                last = FilingStudioError(res.status_code, _describe(res.status_code, body)[0], None, body)
+                continue
+            _raise_for(res.status_code, body)
+        if isinstance(last, FilingStudioError):
+            raise last
+        raise self._unreachable(last)
+
+    async def search(self, ticker: str, q: str, *, type: Optional[str] = None,
+                     period: Optional[str] = None, forms: Optional[str] = None,
+                     limit: Optional[int] = None, offset: Optional[int] = None) -> SearchResult:
+        body = await self._request("GET", "/v1/search",
+                                   params=self._search_params(ticker, q, type, period, forms, limit, offset))
+        return self._search(body, type or "all")
+
+    async def verify(self, ticker: str, *, metric: Optional[str] = None, value: Optional[float] = None,
+                     period: Optional[str] = None, claim: Optional[str] = None) -> VerifyResult:
+        payload = _clean({"ticker": ticker.upper(), "metric": metric, "value": value,
+                          "period": period, "claim": claim})
+        return self._verify(await self._request("POST", "/v1/verify", json=payload))
+
+    async def trace(self, trace_id: str, *, include_context: bool = True) -> Optional[TraceDetail]:
+        return self._trace(await self._request("GET", self._trace_path(trace_id, include_context)))
+
+    async def filings(self, ticker: str, *, form: Optional[str] = None, year: Optional[str] = None,
+                      limit: Optional[int] = None) -> FilingsResult:
+        t = ticker.upper()
+        body = await self._request("GET", f"/v1/filings/{quote(t, safe='')}",
+                                   params=_clean({"form": form, "year": year, "limit": limit}))
+        return self._filings(body, t)
+
+    async def coverage(self, ticker: str) -> CoverageResult:
+        t = ticker.upper()
+        return self._coverage(await self._request("GET", "/v1/coverage", params={"ticker": t}), t)
+
+    async def table(self, ticker: str, accession: str, table_id: str, *,
+                    format: str = "records") -> TableResult:
+        return self._table(await self._request("GET", self._table_path(ticker, accession, table_id),
+                                               params={"format": format}))

filingstudio/errors.py

@@ -0,0 +1,38 @@
+"""Errors. None of them ever carries the API key: it travels in a header, and
+messages are built from the status and the API's own error body only."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .models import IndexState
+
+
+class FilingStudioError(Exception):
+    """Any non-2xx answer (or an unreachable API, status 0)."""
+
+    def __init__(self, status: int, message: str, code: Optional[str] = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.code = code
+        self.body = body
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return f"{self.message} (HTTP {self.status})" if self.status else self.message
+
+
+class RateLimitError(FilingStudioError):
+    """429: the daily limit is spent. `index_state.note` is the honest sentence
+    to show a user: it says nothing about what the filings contain."""
+
+    def __init__(self, index_state: IndexState, body: Any = None) -> None:
+        super().__init__(429, index_state.note or "Daily request limit reached.", "rate_limited", body)
+        self.index_state = index_state
+
+
+class NotConfigured(FilingStudioError):
+    """No API key was given."""
+
+    def __init__(self) -> None:
+        super().__init__(0, "FilingStudio requires an api_key.", "not_configured")

filingstudio/models.py

@@ -0,0 +1,194 @@
+"""Typed results. Every field that claims to be "from the filing"
+(`printed_text`, `text`, context rows) is verbatim text the API returned.
+`IndexState` keeps "searched, genuinely not found" apart from "index
+incomplete" and "service unavailable". Unknown fields are kept, not dropped,
+so a newer API never breaks an older client."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Coverage = Literal["indexed", "empty", "incomplete", "unavailable", "unknown"]
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class IndexState(_Model):
+    coverage: Coverage = "unknown"
+    note: Optional[str] = None
+
+    @property
+    def searched(self) -> bool:
+        """True only when a populated index actually answered."""
+        return self.coverage in ("indexed", "empty")
+
+
+class EvidenceLinks(_Model):
+    highlight: Optional[str] = None
+    viewer: Optional[str] = None
+    edgar: Optional[str] = None
+
+
+class EvidenceSource(_Model):
+    accession: Optional[str] = None
+    form: Optional[str] = None
+    filed_date: Optional[str] = Field(default=None, alias="filedDate")
+    table_id: Optional[str] = Field(default=None, alias="tableId")
+    row_index: Optional[int] = Field(default=None, alias="rowIndex")
+    phys_col: Optional[int] = Field(default=None, alias="physCol")
+    doc_source: Optional[str] = Field(default=None, alias="docSource")
+    block_index: Optional[int] = Field(default=None, alias="blockIndex")
+    anchor: Optional[str] = None
+
+
+class ContextRow(_Model):
+    label: Optional[str] = None
+    printed_text: Optional[str] = Field(default=None, alias="printedText")
+    is_source: bool = Field(default=False, alias="isSource")
+
+
+class TraceDetail(_Model):
+    trace_id: str = Field(alias="traceId")
+    kind: Optional[str] = None
+    ticker: Optional[str] = None
+    accession: Optional[str] = None
+    table_id: Optional[str] = Field(default=None, alias="tableId")
+    row_index: Optional[int] = Field(default=None, alias="rowIndex")
+    concept: Optional[str] = None
+    table_heading: Optional[str] = Field(default=None, alias="tableHeading")
+    row_label: Optional[str] = Field(default=None, alias="rowLabel")
+    printed_value: Optional[str] = Field(default=None, alias="printedValue")
+    numeric_value: Optional[float] = Field(default=None, alias="numericValue")
+    text: Optional[str] = None
+    source_excerpt: Optional[str] = Field(default=None, alias="sourceExcerpt")
+    header_cells: List[Dict[str, Any]] = Field(default_factory=list, alias="headerCells")
+    viewer_url: Optional[str] = Field(default=None, alias="viewerUrl")
+    links: EvidenceLinks = Field(default_factory=EvidenceLinks)
+    context: List[ContextRow] = Field(default_factory=list)
+
+
+class SearchCell(_Model):
+    kind: Literal["cell"] = "cell"
+    value: Optional[float] = None
+    printed_text: Optional[str] = Field(default=None, alias="printedText")
+    label: Optional[str] = None
+    period: Optional[str] = None
+    units: Optional[str] = None
+    trace_id: Optional[str] = Field(default=None, alias="traceId")
+    viewer_url: Optional[str] = Field(default=None, alias="viewerUrl")
+    links: EvidenceLinks = Field(default_factory=EvidenceLinks)
+    source: EvidenceSource = Field(default_factory=EvidenceSource)
+
+
+class SearchPassage(_Model):
+    kind: Literal["passage"] = "passage"
+    text: Optional[str] = None
+    trace_id: Optional[str] = Field(default=None, alias="traceId")
+    viewer_url: Optional[str] = Field(default=None, alias="viewerUrl")
+    links: EvidenceLinks = Field(default_factory=EvidenceLinks)
+    source: EvidenceSource = Field(default_factory=EvidenceSource)
+
+
+SearchHit = Union[SearchCell, SearchPassage, Dict[str, Any]]
+
+
+def parse_hit(raw: Any) -> SearchHit:
+    if isinstance(raw, dict):
+        kind = raw.get("kind")
+        if kind == "cell":
+            return SearchCell.model_validate(raw)
+        if kind == "passage":
+            return SearchPassage.model_validate(raw)
+        return raw
+    return {"value": raw}
+
+
+class Pagination(_Model):
+    limit: Optional[int] = None
+    offset: Optional[int] = None
+    returned: Optional[int] = None
+    next_offset: Optional[int] = Field(default=None, alias="nextOffset")
+
+
+class SearchResult(_Model):
+    type: str = "all"
+    results: List[Any] = Field(default_factory=list)
+    index_state: IndexState = Field(default_factory=IndexState, alias="indexState")
+    pagination: Optional[Pagination] = None
+    note: Optional[str] = None
+
+    @property
+    def cells(self) -> List[SearchCell]:
+        return [h for h in self.results if isinstance(h, SearchCell)]
+
+    @property
+    def passages(self) -> List[SearchPassage]:
+        return [h for h in self.results if isinstance(h, SearchPassage)]
+
+
+class FilingRef(_Model):
+    accession: str
+    form: Optional[str] = None
+    filed_date: Optional[str] = Field(default=None, alias="filedDate")
+    period_of_report: Optional[str] = Field(default=None, alias="periodOfReport")
+    viewer_url: Optional[str] = Field(default=None, alias="viewerUrl")
+    edgar_url: Optional[str] = Field(default=None, alias="edgarUrl")
+
+
+class FilingsResult(_Model):
+    ticker: str
+    filings: List[FilingRef] = Field(default_factory=list)
+    index_state: IndexState = Field(default_factory=IndexState, alias="indexState")
+    pagination: Optional[Pagination] = None
+    note: Optional[str] = None
+
+
+class VerifyReceipt(_Model):
+    kind: Optional[str] = None
+    value: Optional[float] = None
+    printed_text: Optional[str] = Field(default=None, alias="printedText")
+    label: Optional[str] = None
+    period: Optional[str] = None
+    units: Optional[str] = None
+    trace_id: Optional[str] = Field(default=None, alias="traceId")
+    viewer_url: Optional[str] = Field(default=None, alias="viewerUrl")
+    links: EvidenceLinks = Field(default_factory=EvidenceLinks)
+    reason: Optional[str] = None
+    source: EvidenceSource = Field(default_factory=EvidenceSource)
+
+
+Verdict = Literal["supported", "unsupported", "ambiguous", "unavailable"]
+
+
+class VerifyResult(_Model):
+    verdict: Verdict = "unavailable"
+    claim: Optional[Dict[str, Any]] = None
+    receipts: List[VerifyReceipt] = Field(default_factory=list)
+    conflicting: List[VerifyReceipt] = Field(default_factory=list)
+    actual: List[VerifyReceipt] = Field(default_factory=list)
+    reason: Optional[str] = None
+    index_state: IndexState = Field(default_factory=IndexState, alias="indexState")
+
+    @property
+    def supported(self) -> bool:
+        return self.verdict == "supported"
+
+
+class CoverageResult(_Model):
+    ticker: str
+    indexed: bool = False
+    rows_indexed: Optional[int] = Field(default=None, alias="rowsIndexed")
+    prose_blocks: Optional[int] = Field(default=None, alias="proseBlocks")
+    earliest_filed: Optional[str] = Field(default=None, alias="earliestFiled")
+    latest_filed: Optional[str] = Field(default=None, alias="latestFiled")
+    note: Optional[str] = None
+
+
+class TableResult(_Model):
+    data: Dict[str, Any] = Field(default_factory=dict)
+    provenance: Dict[str, Any] = Field(default_factory=dict)
+    links: Dict[str, Any] = Field(default_factory=dict)

filingstudio/research.py

@@ -0,0 +1,411 @@
+"""
+EXPERIMENTAL. A research loop over the evidence layer: a model you supply
+drives the search, and every claim in its answer has a receipt.
+
+    from filingstudio import FilingStudio
+    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=FilingStudio(api_key=KEY),
+                 on_step=lambda label, detail: print(label, detail))
+    res.answer          # prose citing [n]
+    res.sources[n-1]    # the receipt behind [n]: a SearchCell or SearchPassage
+    res.hard_stop       # which limit ended the loop, if any
+
+The loop (every step reports through `on_step`):
+
+  1. PLAN     the model turns the question into short search terms.
+  2. SEARCH   each term runs against the company's filings; hits are pooled.
+  3. ASSESS   the model reads the pool, writes a working draft citing [n],
+              and either says "enough" or asks for more terms.
+  4. repeat 2-3 until it says enough, or a HARD STOP hits.
+  5. WRITE    the final answer, from the evidence only.
+
+Hard stops: rounds, searches, model calls, evidence items, wall-clock seconds.
+When one hits, the last model call is a REORGANIZE pass: it is handed the
+working draft and the evidence and told to reorder and tidy, adding nothing.
+So the loop always ends with an answer, and never with a guess.
+
+The model writes sentences. It never invents a number or a quote: those come
+only from search hits, which are the same receipts a drawer shows. Citations
+to items that do not exist are stripped. With no evidence at all, the honest
+answer is "no filing evidence attached", not a confident guess.
+
+This module sits beside the client on purpose: the client never guesses, and
+this helper is where a model is allowed to speak. Treat its output as prose
+over receipts, not as evidence.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .client import FilingStudio
+from .models import IndexState, SearchCell, SearchPassage
+
+LLM = Callable[[str, str, bool], str]
+"""(system, user, json_mode) -> assistant text."""
+OnStep = Callable[[str, Optional[str]], None]
+
+Evidence = Union[SearchCell, SearchPassage]
+
+
+class ResearchSource(BaseModel):
+    n: int
+    item: Evidence
+
+
+class ResearchStep(BaseModel):
+    label: str
+    detail: Optional[str] = None
+
+
+class ResearchAnswer(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    ticker: str
+    question: str
+    answer: str
+    sources: List[ResearchSource] = Field(default_factory=list)
+    steps: List[ResearchStep] = Field(default_factory=list)
+    hard_stop: Optional[str] = Field(default=None, alias="hardStop")
+    evidence_thin: bool = Field(default=False, alias="evidenceThin")
+    note: Optional[str] = None
+    index_state: IndexState = Field(default_factory=IndexState, alias="indexState")
+
+
+NO_EVIDENCE = (
+    "No filing evidence attached for that. This answers only from filings it "
+    "can show a receipt for, and it found none for this question."
+)
+
+_RULES = """Hard rules:
+- Use ONLY the evidence provided. Do not add numbers, quotes, or facts that are
+  not in the evidence list.
+- When you state something drawn from an item, cite it inline as [n] using that
+  item's number. Cite the specific item, not a range.
+- Never wrap your own words in quotation marks as if they were from the filing.
+  Only the evidence text is the filing's words.
+- If the evidence is thin or does not address the question, say so plainly.
+  Do not fill the gap with general knowledge."""
+
+
+def _sys_plan(app: str) -> str:
+    return f"""You are the research analyst inside {app}.
+Turn the user's question about a company into up to 10 hyper-relevant short
+search terms for a full-text search over that company's SEC filings (10-K,
+10-Q). Each term is 1-4 words the filing itself would print: product names,
+segment names, line items, risk-factor phrases, management's own wording.
+Cover the question from several angles (the thing itself, its drivers, its
+risks, the numbers that measure it). No whole questions, no filler words, no
+near-duplicates. Reply with JSON only: {{"queries": ["...", "..."]}}"""
+
+
+def _sys_assess(app: str) -> str:
+    return f"""You are the research analyst inside {app}.
+You are given a question, the search terms tried so far, and a numbered list of
+EVIDENCE items found in the company's SEC filings (verbatim quotes and printed
+figures). Write a working DRAFT answer from the evidence, then decide whether
+more searching would help.
+{_RULES}
+Reply with JSON only:
+{{"draft": "2-5 sentences citing [n]",
+  "enough": true or false,
+  "next_queries": ["up to 10 NEW short search terms not tried yet, only if enough is false"],
+  "gap": "one line on what is still missing, or empty"}}"""
+
+
+def _sys_write(app: str) -> str:
+    return f"""You are the research analyst inside {app}.
+You will be given a question about a company and a numbered list of EVIDENCE
+items retrieved from that company's SEC filings. Each item is either a verbatim
+quote from the filing or a printed figure with its label.
+{_RULES}
+- Be concise: a short, direct answer of 2-5 sentences. No preamble."""
+
+
+def _sys_reorganize(app: str) -> str:
+    return f"""You are the research analyst inside {app}.
+The research budget is spent. You are given the question, a working DRAFT, and
+the numbered EVIDENCE the draft cites. Produce the final answer by REORDERING
+and tidying the draft so it answers the question directly and reads cleanly.
+Do NOT add any new information, number, quote, or claim that is not already in
+the draft or the evidence. Keep every [n] citation pointing at the same item.
+If the draft says the evidence is thin, keep saying so.
+{_RULES}
+- 2-5 sentences. No preamble."""
+
+
+class _Budget:
+    def __init__(self, *, max_rounds: int, max_searches: int, max_llm_calls: int,
+                 max_items: int, time_budget_s: float) -> None:
+        self.started = time.monotonic()
+        self.rounds = 0
+        self.searches = 0
+        self.llm_calls = 0
+        self.max_rounds = max_rounds
+        self.max_searches = max_searches
+        self.max_llm_calls = max_llm_calls
+        self.max_items = max_items
+        self.time_budget_s = time_budget_s
+
+    def stop_reason(self, items: int) -> Optional[str]:
+        if time.monotonic() - self.started > self.time_budget_s:
+            return f"time budget ({int(self.time_budget_s)}s)"
+        if self.rounds >= self.max_rounds:
+            return f"round limit ({self.max_rounds})"
+        if self.searches >= self.max_searches:
+            return f"search limit ({self.max_searches})"
+        if self.llm_calls >= self.max_llm_calls - 1:  # keep one call for the ending
+            return f"model-call limit ({self.max_llm_calls})"
+        if items >= self.max_items:
+            return f"evidence limit ({self.max_items} items)"
+        return None
+
+
+def _key(it: Evidence) -> str:
+    if it.trace_id:
+        return it.trace_id
+    if isinstance(it, SearchCell):
+        return f"{it.label}|{it.printed_text}"
+    return f"passage|{it.text}"
+
+
+def evidence_prompt(ticker: str, question: str, items: List[Evidence], *,
+                    tried: Optional[List[str]] = None, draft: str = "") -> str:
+    lines = [f"Company: {ticker}", f"Question: {question}"]
+    if tried:
+        lines.append("Search terms tried: " + "; ".join(tried))
+    lines += ["", "EVIDENCE:"]
+    for i, it in enumerate(items, 1):
+        if isinstance(it, SearchPassage):
+            lines.append(f'[{i}] Filing quote: "{it.text or ""}"')
+        else:
+            label = it.label or "figure"
+            printed = it.printed_text or (str(it.value) if it.value is not None else "")
+            period = f", {it.period}" if it.period else ""
+            lines.append(f'[{i}] {label}: printed "{printed}"{period}')
+    if draft:
+        lines += ["", "DRAFT:", draft]
+    return "\n".join(lines)
+
+
+def drop_uncited(text: str, n_sources: int) -> str:
+    """A citation to an item that does not exist is a hallucinated receipt;
+    strip the marker rather than render a dead link."""
+    return re.sub(r"\[(\d+)\]", lambda m: m.group(0) if 1 <= int(m.group(1)) <= n_sources else "", text)
+
+
+def _llm_json(llm: LLM, system: str, user: str) -> dict:
+    raw = llm(system, user, True)
+    try:
+        out = json.loads(raw)
+    except ValueError:
+        m = re.search(r"\{.*\}", raw, re.S)
+        out = json.loads(m.group(0)) if m else {}
+    return out if isinstance(out, dict) else {}
+
+
+def answer(
+    question: str,
+    ticker: str,
+    *,
+    llm: Optional[LLM],
+    client: Optional[FilingStudio] = None,
+    api_key: Optional[str] = None,
+    max_rounds: int = 2,
+    terms_per_round: int = 10,
+    time_budget_s: float = 25.0,
+    max_searches: Optional[int] = None,
+    max_llm_calls: int = 5,
+    max_items: int = 30,
+    hits_per_search: int = 4,
+    workers: int = 5,
+    on_step: Optional[OnStep] = None,
+    app_name: str = "this app",
+) -> ResearchAnswer:
+    """Run the loop. `llm(system, user, json_mode) -> str` is any chat model.
+    With `llm=None`, one plain search runs and the evidence is returned with
+    no prose. Pass a `client` or an `api_key`."""
+    fs = client or FilingStudio(api_key)
+    t = ticker.upper()
+    steps: List[ResearchStep] = []
+    max_searches = max_searches if max_searches is not None else max_rounds * terms_per_round
+
+    def step(label: str, detail: Optional[str] = None) -> None:
+        steps.append(ResearchStep(label=label, detail=detail))
+        if on_step:
+            on_step(label, detail)
+
+    def hits_of(res) -> List[Evidence]:
+        return [h for h in res.results if isinstance(h, (SearchCell, SearchPassage))]
+
+    if llm is None:
+        step("Searching filings", question)
+        res = fs.search(t, question, limit=max(hits_per_search, 8))
+        items = hits_of(res)
+        sources = [ResearchSource(n=i + 1, item=it) for i, it in enumerate(items)]
+        return ResearchAnswer(
+            ticker=t, question=question,
+            answer=("No model was supplied, so no prose was written; the filing "
+                    "evidence is below.") if sources else NO_EVIDENCE,
+            sources=sources, steps=steps, evidenceThin=len(sources) < 2,
+            indexState=res.index_state,
+        )
+
+    budget = _Budget(max_rounds=max_rounds, max_searches=max_searches,
+                     max_llm_calls=max_llm_calls, max_items=max_items,
+                     time_budget_s=time_budget_s)
+    pool: List[Evidence] = []
+    seen: set = set()
+    tried: List[str] = []
+    last_state = IndexState()
+    draft = ""
+    hard_stop: Optional[str] = None
+
+    def add_hits(items: List[Evidence]) -> int:
+        added = 0
+        for it in items:
+            k = _key(it)
+            if k in seen or len(pool) >= max_items:
+                continue
+            seen.add(k)
+            pool.append(it)
+            added += 1
+        return added
+
+    def run_searches(queries: List[str]) -> None:
+        nonlocal last_state
+        todo: List[str] = []
+        lower_tried = {x.lower() for x in tried}
+        for q in queries:
+            q = str(q).strip()
+            if not q or q.lower() in lower_tried or q.lower() in {x.lower() for x in todo}:
+                continue
+            if budget.searches + len(todo) >= max_searches:
+                break
+            todo.append(q)
+        if not todo:
+            return
+        budget.searches += len(todo)
+        tried.extend(todo)
+        step("Searching filings", " · ".join(todo))
+
+        def one(q: str):
+            try:
+                return fs.search(t, q, limit=hits_per_search)
+            except Exception as exc:  # noqa: BLE001 - one bad term must not sink the round
+                return exc
+
+        with ThreadPoolExecutor(max_workers=max(1, workers)) as ex:
+            results = list(ex.map(one, todo))
+        for q, res in zip(todo, results):
+            if isinstance(res, Exception):
+                step("Search failed", f"“{q}”: {type(res).__name__}")
+                continue
+            last_state = res.index_state
+            n = add_hits(hits_of(res))
+            step("Found receipts", f"{n} new for “{q}” · {len(pool)} total")
+
+    # 1. PLAN
+    step("Planning searches", question)
+    try:
+        budget.llm_calls += 1
+        plan = _llm_json(llm, _sys_plan(app_name), f"Company: {t}\nQuestion: {question}")
+        queries = [str(q) for q in (plan.get("queries") or [])][:terms_per_round]
+    except Exception as exc:  # noqa: BLE001 - degrade, never crash
+        queries = []
+        step("Planner unavailable", f"{type(exc).__name__}; searching the question as typed")
+    if not queries:
+        queries = [question]
+
+    # 2-4. SEARCH / ASSESS
+    while True:
+        budget.rounds += 1
+        run_searches(queries)
+        if pool:
+            step("Reading evidence", f"{len(pool)} receipts")
+            try:
+                budget.llm_calls += 1
+                verdict = _llm_json(llm, _sys_assess(app_name),
+                                    evidence_prompt(t, question, pool, tried=tried))
+            except Exception as exc:  # noqa: BLE001
+                step("Assessment unavailable", type(exc).__name__)
+                hard_stop = "model error"
+                break
+            draft = str(verdict.get("draft") or draft)
+            if verdict.get("enough") or not verdict.get("next_queries"):
+                step("Enough evidence", verdict.get("gap") or None)
+                break
+            queries = [str(q) for q in verdict.get("next_queries") or []][:terms_per_round]
+            step("Need more", verdict.get("gap") or ", ".join(queries))
+        else:
+            step("Rethinking search terms", "no receipts yet")
+            queries = [question] if question.lower() not in {x.lower() for x in tried} else []
+            if not queries:
+                break
+        reason = budget.stop_reason(len(pool))
+        if reason:
+            hard_stop = reason
+            break
+
+    sources = [ResearchSource(n=i + 1, item=it) for i, it in enumerate(pool)]
+    if not sources:
+        note = last_state.note if last_state.coverage == "incomplete" else None
+        step("No evidence found", note)
+        return ResearchAnswer(ticker=t, question=question, answer=NO_EVIDENCE,
+                              evidenceThin=True, note=note, steps=steps,
+                              hardStop=hard_stop, indexState=last_state)
+
+    # 5. WRITE, or on a hard stop REORGANIZE the draft without adding anything.
+    try:
+        budget.llm_calls += 1
+        if hard_stop:
+            step("Hard stop", hard_stop)
+            step("Reorganizing draft into the answer", "no new information")
+            if draft:
+                text = llm(_sys_reorganize(app_name),
+                           evidence_prompt(t, question, pool, draft=draft)
+                           + "\n\nReorder and tidy the DRAFT into the final answer now. Add nothing.",
+                           False)
+            else:
+                text = llm(_sys_write(app_name),
+                           evidence_prompt(t, question, pool)
+                           + "\n\nWrite the answer now, citing items as [n].", False)
+        else:
+            step("Writing answer", f"{len(pool)} receipts")
+            text = llm(_sys_write(app_name),
+                       evidence_prompt(t, question, pool)
+                       + "\n\nWrite the answer now, citing items as [n].", False)
+    except Exception as exc:  # noqa: BLE001 - degrade, never crash
+        if draft:
+            return ResearchAnswer(
+                ticker=t, question=question, answer=drop_uncited(draft, len(sources)),
+                sources=sources, evidenceThin=len(sources) < 2, steps=steps, hardStop=hard_stop,
+                note=f"Final pass failed ({type(exc).__name__}); showing the working draft.",
+                indexState=last_state)
+        return ResearchAnswer(
+            ticker=t, question=question,
+            answer="The filing evidence below was retrieved, but the writing model could not be reached to summarize it.",
+            sources=sources, evidenceThin=len(sources) < 2, steps=steps, hardStop=hard_stop,
+            note=f"Synthesis error: {type(exc).__name__}", indexState=last_state)
+
+    text = drop_uncited(str(text).strip(), len(sources))
+    step("Done", None)
+    note = None
+    if hard_stop:
+        note = (f"Stopped early at the {hard_stop}; "
+                + ("the answer was reorganized from the working draft, nothing added."
+                   if draft else "the answer was written from the receipts found so far."))
+    return ResearchAnswer(ticker=t, question=question, answer=text, sources=sources,
+                          evidenceThin=len(sources) < 2, steps=steps, hardStop=hard_stop,
+                          note=note, indexState=last_state)

filingstudio-0.4.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: filingstudio
+Version: 0.4.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
+Author-email: Filing Studio <support@filingstudio.com>
+License: MIT
+License-File: LICENSE
+Keywords: 10-K,10-Q,api-client,citations,edgar,filings,finance,provenance,sec
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.0
+Provides-Extra: test
+Requires-Dist: anyio>=3; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# filingstudio
+
+Python client for the [Filing Studio](https://filingstudio.com) 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.
+
+```bash
+pip install filingstudio
+```
+
+```python
+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:
+
+```python
+from filingstudio import AsyncFilingStudio
+
+async with AsyncFilingStudio(api_key=key) as fs:
+    cov = await fs.coverage("NVDA")
+```
+
+## The six doors
+
+| method | what it answers |
+|---|---|
+| `search(ticker, q, type=, period=, forms=, limit=, offset=)` | printed rows, tables, and prose matching plain words |
+| `verify(ticker, metric=, value=, period=, claim=)` | is this claim what the filing prints? |
+| `trace(trace_id, include_context=True)` | the exact printed line behind a traceId, with neighbours |
+| `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 |
+
+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)
+
+```python
+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
+
+```bash
+pip install -e .[test]
+pytest
+```
+
+MIT

filingstudio-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+filingstudio/__init__.py,sha256=Xd1ROtPdTinU5ldRy46FCVQMjnGKVXaHdgbHksejM5w,993
+filingstudio/client.py,sha256=uKeRSFFJtUz9kcK_cnBHwwSR6akwz_JPtUFyo_SsDSY,14256
+filingstudio/errors.py,sha256=IcEkePPC1wdiNe79RzU6q9fyM3UdpjS17YKILZSdbHI,1356
+filingstudio/models.py,sha256=KZRHgUgOpjtVbmXDuSsHHNSAnseiGSY4LvM2fitKX-o,7242
+filingstudio/research.py,sha256=qtIh_UQWuKlgpF5fMEWVKSIrRsg9_vAm0bgZXyQWcOo,17094
+filingstudio-0.4.0.dist-info/METADATA,sha256=nwcxoe8jD3djHlKMdhDurB-dJydewnzR42fPoxOOO2U,4914
+filingstudio-0.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+filingstudio-0.4.0.dist-info/licenses/LICENSE,sha256=0N9MXUpOueb0VCrG2YJoMksp8VFEVrsgbeIsEKm00RU,1070
+filingstudio-0.4.0.dist-info/RECORD,,

filingstudio-0.4.0.dist-info/WHEEL

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

filingstudio-0.4.0.dist-info/licenses/LICENSE

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