Metadata-Version: 2.5
Name: timefire
Version: 0.1.1
Summary: Timefire's resolved forecast record as DataFrames, with local signature verification.
Project-URL: Homepage, https://timefire.ai/developers
Project-URL: Documentation, https://timefire.ai/developers/python
Project-URL: Repository, https://github.com/timefire-ai/timefire
Author: Cromwell Works LLC
License-Expression: MIT
License-File: LICENSE
Keywords: ed25519,forecasts,ledger,pandas,stocks,timefire
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Investment
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=15
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# timefire

Timefire's resolved forecast record as DataFrames. Read-only.

```python
import timefire as tf

day = tf.book("2026-08-27")              # one graded book
print(tf.verify("2026-08-27").status)    # verified
```

## What you get

| Call | Returns | Source |
| --- | --- | --- |
| `tf.batches()` | one row per graded book: its verdict (cap-weighted vs SPY) first, then the equal-weighted portfolio vs RSP | files |
| `tf.books()` | every prediction from every graded book | files |
| `tf.book("2026-08-27")` | one book; `.attrs` has its hash, content address, signature and public verification key | files + API |
| `tf.nav()` | the paper portfolio day by day, cap-weighted (the API's `strategy=long_only_cap`, the line Timefire leads with), next to SPY; `tf.nav(weighting="equal")` is the equal-weighted line (`strategy=long_only`) next to RSP | files |
| `tf.stats()` | counts, hit rates and the verdict tally (cap-weighted vs SPY) over graded books, the API's resolved-only fields: hit rates from 2026-04-14 under the published rule, the 69 backtest books apart | files |
| `tf.manifest()` | the export index with sizes and SHA-256 fingerprints | files |
| `tf.ticker("AAPL")` | one ticker's graded observations | API |
| `tf.calibration()` | return deciles, rank buckets, side hit rates | API |
| `tf.verify("2026-08-27")` | local hash and Ed25519 check against the pinned key | API |
| `tf.verify_record(record, "2026-08-27")` | the same check on a verify record you fetched yourself; pass the date you asked for | none |
| `tf.verify_portfolio("2026-08-27")` | one of the book's two portfolios (`"cap"` vs SPY, the default; `"equal"` vs RSP), every number rechecked against the signed book | API |
| `tf.verify_portfolio_record(...)` | the same check on responses you fetched yourself | none |

The data calls return graded books only; a book is graded ten trading days after it was sealed. `verify()` also answers for a book that is still sealed, with the `sealed` status below, and never sees its contents. What each column means: https://timefire.ai/developers/columns. How verification works: https://timefire.ai/developers/verification.

`verify()` returns one of `verified`, `sealed`, `failed`, `legacy-unverifiable`. Books before 2026-04-28 predate exact-signed-bytes custody, so a mismatch there is reported as `legacy-unverifiable`, and only when you asked for a pre-cutoff date. Since timefire#995 those books serve their originally signed bytes and verify; treat `legacy-unverifiable` as a failure.

`verify_portfolio()` returns `verified`, `unsigned-weights` (all checks pass, but the weights are an earlier book's market-cap weights, which its signed payload does not carry), `incomplete` (nothing failed, but a check could not be made), `pending` or `failed`, with a `checks` list. It is a check-for-check port of `@timefire/client`'s `verifyPortfolio`.

## Changelog

- 0.1.1: cap-weighted against SPY is the default series; `weighting="equal"` selects the equal-weighted line against RSP. `stats()` reports the 69 backtest books apart. `verify()` checks the date inside the signed bytes. `verify_portfolio()` checks a book's cap-weighted or equal-weighted portfolio against the signed book.
- 0.1.0: first release.
