Metadata-Version: 2.4
Name: ahasignals-pit
Version: 0.1.1
Summary: Point-in-time financial fact selection and quarterly cash-flow checks
Project-URL: Homepage, https://ahasignals.com/research/point-in-time-financial-data/
Project-URL: Documentation, https://ahasignals.com/examples/ahasignals-pit/v0.1.1/README.md
Project-URL: Source, https://ahasignals.com/examples/ahasignals-pit/v0.1.1/ahasignals_pit-0.1.1.tar.gz
Project-URL: Related benchmark dataset, https://huggingface.co/datasets/AhaSignals/financial-ai-pit-integrity
Project-URL: Related paper, https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7415198
Author: AhaSignals
Maintainer-email: AhaSignals <research@ahasignals.com>
License-Expression: MIT
License-File: LICENSE
Keywords: backtesting,financial-data,point-in-time,reproducibility
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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:

```bash
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:

```bash
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

```bash
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:

```bash
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:

```python
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:

```text
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:

| Field | Contract |
| --- | --- |
| `cik` | String of exactly 10 ASCII digits |
| `taxonomy`, `concept`, `unit` | Nonempty strings; exact match, no alias or currency conversion |
| `start`, `end` | ISO dates; use empty `start` for an instant fact |
| `dimensions` | List of `{axis, member}` objects; unique axes; empty for consolidated scope |
| `cutoff` | Date and time with a known timezone |
| `mode` | `disclosure-reconstruction` or `observed-pipeline` |
| `accession` | Optional exact filing filter, `##########-##-######` |

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](https://ahasignals.com/examples/ahasignals-pit/v0.1.1/ahasignals_pit-0.1.1.tar.gz),
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:

```bash
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](https://ahasignals.com/research/point-in-time-financial-data/)
- [Worked financial query checks](https://ahasignals.com/research/financial-query-correctness/)
- [Related benchmark dataset](https://huggingface.co/datasets/AhaSignals/financial-ai-pit-integrity)
- [Related working paper](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7415198)

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.
