AhaSignals PIT and financial research workflow

Check periods, source versions and financial facts before using them in research. The no-key demo compares a quarter with a half-year from one reviewed filing.

python -m pip install https://ahasignals.com/examples/ahasignals-pit/v0.3.0/ahasignals_pit-0.3.0-py3-none-any.whl
ahasignals-workflow demo --out first-review
ahasignals-workflow replay --input first-review/packet.json

Open first-review/report.md for the Chinese explanation and packet.json for inputs, outputs and a checksum. The reviewed case is not a vendor response.

• Step-by-step guide, Skill download and local MCP
• Workflow reference
• Independent fixed-evidence MCP server

Version 0.3.0 adds a portable Skill companion, four local stdio MCP tools, provider-export inspection and an explicit, separate Tushare HTTPS collector. Core checks and MCP remain offline. Only fetch-tushare makes a network request, when explicitly run with a personal credential. It does not provide credentials, purchase access, infer financial context or validate a vendor's provenance. Do not place tokens in chat, tool arguments, reports or shared notebooks.

Research annotations in workflow_data/period-case.json are CC BY 4.0, attributed to AhaSignals; software is MIT. AI-assisted single-operator research. No trading, account access, live feed or independent assurance is provided.

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, network requests, telemetry, account or API key required during checks. Version 0.3.0 keeps a deliberately narrow contract: checks of supplied facts, not independent source authentication.

Check a historical input before using it

Use audit_batch(payload) or ahasignals-audit check --input audit-input.json to check declared financial feature inputs before a backtest. Create that input with ahasignals-audit example pass > audit-input.json; it is fully synthetic. Reports distinguish PASS, FAIL, UNKNOWN and input/execution ERROR, with stable rule IDs, source assumptions, excluded checks and input hashes. Legacy commands and APIs retain their behavior.

Batch contract, examples and CI gates · External extractor compatibility

A PASS checks supplied declarations; it does not authenticate source documents or certify a backtest. FAIL and UNKNOWN are useful results, not values to replace with zero. The audit command exits 0 for PASS, 1 for FAIL, 2 for ERROR and 3 for UNKNOWN; only 0 should admit data to a workflow requiring these checks.

Reproduce a cutoff comparison

After installation, run:

python3 -m ahasignals_pit.replay > cutoff-replay.json

This bundled, fully synthetic example keeps the fact and selected version fixed. It returns FAIL before declared acceptance, PASS at acceptance in disclosure reconstruction, and UNKNOWN in observation mode because the historical collection time is missing. The saved output contains each exact input and complete report. Changing the cutoff asks a different question; it does not repair a historical backtest. The demonstration exits 0 when it runs successfully, even when its reports contain FAIL or UNKNOWN. Use ahasignals-audit check for CI enforcement.

For the same procedure with selected, previously reviewed issuer facts, see the source-linked replay. Those are constructed uses of real facts, not discovered third-party errors.

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 https://ahasignals.com/examples/ahasignals-pit/v0.3.0/ahasignals_pit-0.3.0-py3-none-any.whl

This command installs the exact reviewed website distribution. Consult the publication status and hashes for its PyPI availability. Once that release is listed on PyPI, the equivalent index command is python3 -m pip install ahasignals-pit==0.3.0. Older stable and candidate releases remain available with their original versions and hashes.

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.3.0, or use the matching source archive from the reviewed website release directory. It includes the source, tests and top-level examples/ directory. No repository access is required. After downloading and extracting it:

cd ahasignals_pit-0.3.0
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.

Python package, evidence datasets and MCP

Use this Python package to check facts you supply from your permitted data source. It does not download issuer data or include a live company database. The AhaSignals Evidence MCP separately exposes a pinned, reviewed evidence snapshot to compatible agent hosts. Its snapshot version and scope are independent of this package. Neither installing this package nor connecting MCP establishes complete filing history, authentic timestamps or an investment recommendation.

Keep original data and licenses with your workflow. Retain unknown fields; do not map different dataset clock semantics to SEC acceptance by renaming a column. Passing schema validation alone does not establish time integrity.

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