AhaSignals PIT

Select financial facts that match a declared historical cutoff, then inspect the period, scope and source version behind each answer. Reconstruct quarterly operating cash flow less cash PP&E without treating cumulative cash flows as a quarter.

Python 3.9 or later. No runtime dependencies. No network requests, telemetry, account or API key required. Version 0.1.0 is an initial alpha release with a deliberately narrow contract.

Install and run

After the release is available on PyPI:

python -m pip install ahasignals-pit==0.1.0
ahasignals-pit input.json
# Equivalent:
python -m ahasignals_pit input.json

For a source checkout, run python -m pip install . from this directory, then:

ahasignals-pit examples/select.json
ahasignals-pit examples/quarterly-cash.json
python -m unittest discover -s tests -v

Both examples are fully synthetic. Their identifiers, amounts, dates, example.org source URL and zero hash do not represent a real issuer or authenticated document. The first selects 120; the second returns quarterly operating cash of 160, cash PP&E of 40 and cash after PP&E of 120 USD. These are arithmetic examples, not investment results.

Python API

import json
from ahasignals_pit import run, select_fact, quarterly_cash

with open('examples/select.json', encoding='utf-8') as stream:
    payload = json.load(stream)
result = select_fact(payload['facts'], payload['query'])
assert result['status'] == 'answer'
print(result['value'], result['inputs'])
# run(payload) dispatches by task: select or quarterly-cash.

The public functions accept JSON-compatible dictionaries and lists. Input field names retain the camelCase contract of the related financial query checker. Output status is answer, withheld or invalid. Never replace a withheld value with zero. The CLI returns exit codes 0, 1 and 2 respectively; it also includes the package version and SHA-256 of the exact input bytes. It accepts a filename or - for stdin, at most 2 MB, and rejects duplicate JSON keys and non-finite constants. Its output includes supplied source references: review inputs before sharing outputs.

Exact fact selection

A query requires:

Every fact needs the identity fields plus finite numeric value, accession, acceptedAt, documentSha256 (64 lowercase hex characters), contextId, and an HTTPS sourceUrl. Values must have absolute magnitude at most 2^53−1. Booleans, NaN and infinity are rejected. Missing or null observedAt is permitted only for disclosure reconstruction. At most 2,000 facts and 32 dimensions per fact are accepted. All supplied facts must have valid required fields, including unmatched facts.

The checker matches the full identity and selects the latest eligible acceptance time. Conflicting values, accessions or hashes at that time produce ambiguous-latest-fact. Duplicate facts with the same value, accession and hash are resolved by context ID. No source file is fetched. A syntactically valid URL, hash or timestamp is not evidence that it is authentic.

Timestamps support 1–9 fractional digits and known offsets through ±14:00. Missing zones, -00:00, leap seconds, invalid calendar dates and years before 1900 are rejected. Comparisons retain nanosecond precision.

Two time modes

• disclosure-reconstruction: use acceptance timestamps supplied by the caller. This reconstructs disclosure eligibility; it does not establish actual historical system access, market dissemination or tradability.
• observed-pipeline: also require observation timestamps at or before cutoff and at or after acceptance. Unknown observation time on any matching accepted candidate withholds the answer instead of silently choosing an older fact.

The caller must establish trustworthy timestamps independently. Collecting a document today cannot establish that the system observed it years ago.

Quarterly cash

Call quarterly_cash(facts, request) with cik, fiscalStart, quarterStart, end, cutoff, and mode. Add computedAt in observed-pipeline mode. See examples/quarterly-cash.json for a complete request.

Only consolidated us-gaap whole-USD facts for these two concepts are supported:

• NetCashProvidedByUsedInOperatingActivities
• PaymentsToAcquirePropertyPlantAndEquipment, expressed as a positive cash outflow

An exact-quarter duration takes precedence. If none matches, current fiscal YTD minus the period ending immediately before the quarter is used. Missing prior periods withhold an answer. A matching but ineligible or ambiguous direct quarter also withholds rather than falling back. The caller supplies and verifies the issuer's fiscal calendar; the tool only checks date validity, ordering and a 60–120-day quarter length.

All selected facts and filing versions remain in inputs. Different filing vintages may be combined; review their accessions and presentation comparability before use. Fractional cash dollars, out-of-range results and negative derived cash PP&E are withheld. In observed-pipeline mode, computation must occur after all input observations and no later than cutoff.

cashAfterPpe excludes acquisitions, noncash additions, leases and other investment spending. It is not a universal free-cash-flow definition. No price data, factor returns, security universe or backtest performance is supplied.

Research and citation

• Point-in-time financial data research
• Worked financial query checks
• Related benchmark dataset
• Related working paper

This package implements financial-query rules. It is not the frozen PIT benchmark scorer and does not reproduce the paper's model scores. Public calibration cases are not held-out evaluation. External datasets and papers retain their own versions and licenses; no third-party document bodies are bundled.

For software use, cite: AhaSignals. AhaSignals PIT, version 0.1.0. Include the source commit and input dataset version used in your analysis. Cite the relevant paper separately when its research is used.

License and scope

Code, documentation, tests and synthetic examples in this distribution: MIT, copyright AhaSignals. No attribution link or network call is required to execute the package. Dataset rights are separate from software rights.

AhaSignals is an independent research publisher, unaffiliated with referenced regulators, issuers and platforms. Third-party names are factual source or compatibility references. Research and education only; no investment, trading, legal, accounting or tax advice. Passing these checks does not certify a backtest or establish predictive value.