ahasignals-pit

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.1 is an alpha release with a deliberately narrow contract.

Quick start after pip install

No GitHub access, source checkout, API key or downloaded example file is needed. Use the same Python interpreter to install and run the package:

python3 -m pip install --upgrade ahasignals-pit==0.1.1

1. Create and run the bundled fact example

Run these commands from any writable directory:

python3 -m ahasignals_pit --example select > select-example.json
python3 -m ahasignals_pit select-example.json

The first command creates select-example.json in your current directory. The second reads it and prints a JSON result with status: "answer", reason: "latest-eligible-exact-context" and value: 120, plus the supplied source fields, package version and input hash. Both commands exit successfully.

2. Try the quarterly cash example

python3 -m ahasignals_pit --example quarterly-cash > quarterly-cash.json
python3 -m ahasignals_pit quarterly-cash.json

Expected fields: status: "answer", operatingCash: 160, cashPpe: 40, cashAfterPpe: 120, unit: "USD". The example computes (280 − 120) − (90 − 50).

Both examples are fully synthetic. Their identifiers, amounts, dates, example.org URL and zero hash do not represent a real issuer or authenticated document. These are arithmetic examples, not investment results. --example prints bundled JSON to stdout and exits with code 0; it does not fetch data or write a file itself. The shell's > redirection creates or overwrites the named file, so choose a new filename if you have an existing one you want to keep.

3. Complete JSON example you can copy

This alternative also creates its own input file. On macOS or Linux, copy the entire block, including the final JSON line:

cat > input.json <<'JSON'
{
  "exampleKind": "fully-synthetic-not-company-data",
  "task": "select",
  "facts": [
    {
      "cik": "0000000001",
      "taxonomy": "us-gaap",
      "concept": "NetCashProvidedByUsedInOperatingActivities",
      "unit": "USD",
      "start": "2025-01-01",
      "end": "2025-03-31",
      "dimensions": [],
      "value": 120,
      "accession": "0000000001-25-000001",
      "acceptedAt": "2025-05-01T00:00:00Z",
      "observedAt": "2025-05-02T00:00:00Z",
      "sourceUrl": "https://example.org/synthetic-filing",
      "documentSha256": "0000000000000000000000000000000000000000000000000000000000000000",
      "contextId": "synthetic-q1"
    }
  ],
  "query": {
    "cik": "0000000001",
    "taxonomy": "us-gaap",
    "concept": "NetCashProvidedByUsedInOperatingActivities",
    "unit": "USD",
    "start": "2025-01-01",
    "end": "2025-03-31",
    "dimensions": [],
    "cutoff": "2025-09-01T00:00:00Z",
    "mode": "disclosure-reconstruction"
  }
}
JSON
python3 -m ahasignals_pit input.json

The expected answer is again 120. If using another shell, save the JSON object between the two delimiter lines into a UTF-8 file named input.json, then run python3 -m ahasignals_pit input.json from that file's directory.

Python API: no local files required

Paste this complete example into Python after installation:

from ahasignals_pit import select_fact

# Fully synthetic data, not a real issuer or authenticated document.
facts = [{'cik': '0000000001',
  'taxonomy': 'us-gaap',
  'concept': 'NetCashProvidedByUsedInOperatingActivities',
  'unit': 'USD',
  'start': '2025-01-01',
  'end': '2025-03-31',
  'dimensions': [],
  'value': 120,
  'accession': '0000000001-25-000001',
  'acceptedAt': '2025-05-01T00:00:00Z',
  'observedAt': '2025-05-02T00:00:00Z',
  'sourceUrl': 'https://example.org/synthetic-filing',
  'documentSha256': '0000000000000000000000000000000000000000000000000000000000000000',
  'contextId': 'synthetic-q1'}]
query = {'cik': '0000000001',
 'taxonomy': 'us-gaap',
 'concept': 'NetCashProvidedByUsedInOperatingActivities',
 'unit': 'USD',
 'start': '2025-01-01',
 'end': '2025-03-31',
 'dimensions': [],
 'cutoff': '2025-09-01T00:00:00Z',
 'mode': 'disclosure-reconstruction'}
result = select_fact(facts, query)
assert result['status'] == 'answer'
assert result['value'] == 120
print(result['value'])

Expected output:

120

run(payload) dispatches by task (select or quarterly-cash). quarterly_cash(facts, request) accepts the structure shown by python3 -m ahasignals_pit --example quarterly-cash.

Input files and CLI errors

Installing a package does not create an input.json file in your working directory. For your own research input, pass the path to a file you have already created. Relative paths are resolved from the directory where you run the command, not from the package installation directory.

• Input file not found: create a bundled example as above or correct the path.
• Cannot read input file: check that the path is a readable file, not a directory.
• Invalid JSON syntax: the file exists but its JSON is malformed.
• status: "invalid": valid JSON was read, but the task or required fields do not match the contract.
• status: "withheld": the request cannot produce an answer under the declared rules. Inspect reason; do not replace the value with zero.

The CLI accepts a filename or - for stdin, at most 2 MB, and rejects duplicate keys and non-finite constants. Exit codes are 0 for an answer, 1 for withheld, and 2 for invalid input or a file-reading error. Results include the package version and SHA-256 of the input bytes. ahasignals-pit is also installed as a console command; python3 -m ahasignals_pit avoids dependence on whether your shell can find that command on PATH. Output includes supplied source references: review inputs before sharing outputs.

The Python functions accept JSON-compatible dictionaries and lists. Field names retain the camelCase contract of the related financial query checker.

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. Run python3 -m ahasignals_pit --example quarterly-cash for a complete request after installation.

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.

Public source and development tests

The development repository is private. The MIT-licensed source distribution is public: download version 0.1.1, or choose the source distribution under the PyPI project's release files. It includes the source, tests and top-level examples/ directory. No repository access is required. After downloading and extracting it:

cd ahasignals_pit-0.1.1
python3 -m pip install .
python3 -m unittest discover -s tests -v

These development instructions are optional; the quick starts above only need the installed package. The example filename uses a hyphen: quarterly-cash.json.

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.1. 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.