Metadata-Version: 2.4
Name: edgar-pit-clock
Version: 0.1.0
Summary: Zero-dependency point-in-time SEC EDGAR acceptanceDateTime to NYSE trading-session router, One-Document-One-Witness accession normalizer, and Purged Walk-Forward splitter.
Author-email: Starling Quantitative Research <founder@starlingquant.com>
License: MIT
Project-URL: Homepage, https://starlingquant.com
Project-URL: Repository, https://github.com/starlingquant/edgar-pit-clock
Project-URL: Documentation, https://starlingquant.com/guides/point-in-time-alternative-data-and-survivorship-free-panels
Project-URL: Scorecard, https://starlingquant.com/scorecard
Project-URL: MachineReference, https://starlingquant.com/llms-full.txt
Keywords: quantitative-finance,sec-edgar,point-in-time,alternative-data,lookahead-bias,walk-forward,market-microstructure
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# `edgar-pit-clock` — Point-in-Time SEC EDGAR Timestamp & Session Router

**Zero-dependency Python utility for eliminating the `4:15 PM` SEC `filingDate` lookahead trap, normalizing `One-Document-One-Witness` EDGAR accession provenance, and enforcing Purged Walk-Forward Cross-Validation embargoes.**

Built and maintained by **[Starling Quantitative Research](https://starlingquant.com)** (*"They Trade the Headlines. We Trade the Fine Print."*).

---

## Why This Exists: The `4:15 PM` Filing Trap

Naive equity backtests align corporate disclosures (`10-K`, `10-Q`, `8-K`, `Form 4`, `Schedule 13D`) by fiscal period-end (`fp`) or calendar `filingDate`. Even `filingDate` leaks a full trading session of lookahead bias whenever a company files after the `16:00:00 ET` closing bell (for example, at `16:15:04 ET`), because a daily close-to-close backtest assumes execution at `16:00:00 ET`—fifteen minutes before the filing hit EDGAR.

`edgar-pit-clock` enforces strict point-in-time filtration using down-to-the-second SEC server `acceptanceDateTime` across the full NYSE holiday calendar:

| Filing `acceptanceDateTime` (`ET`) | `MarketSession` | Intraday Daemon | Daily Batch Replay |
| :--- | :--- | :--- | :--- |
| `< 09:30:00 ET` (NYSE Trading Day) | `PRE_MARKET` | Wait for `Open(T_0)` | `Open(T_0)` |
| `09:30:00 – 15:59:59 ET` | `REGULAR_SESSION` | Live `ArrivalMid` | `Open(T+1)` *(Conservative)* |
| `>= 16:00:00 ET` | `AFTER_HOURS` | Next Session `Open(T+1)` | `Open(T+1)` |
| Weekend / NYSE Holiday | `NON_TRADING_DAY` | Next Session `Open(T+1)` | `Open(T+1)` |

---

## Quickstart

```bash
pip install edgar-pit-clock
```

```python
from edgar_pit_clock import (
    align_filing_to_market_bar,
    normalize_cik10,
    normalize_sec_artifact_id,
    purged_walk_forward_splits,
)

# 1. Friday 16:15:04 ET Form 8-K -> Routes cleanly to Monday Open (never Friday Close)
bar = align_filing_to_market_bar("2026-11-13T16:15:04-05:00")
print(bar.market_session, bar.daily_batch_bar_date, bar.daily_batch_price_field)
# -> MarketSession.AFTER_HOURS 2026-11-16 OPEN

# 2. One-Document-One-Witness provenance key (prevents multi-parser double-counting)
doc_id = normalize_sec_artifact_id("0000320193-26-000077")
cik = normalize_cik10(320193)
# -> doc_id == "SEC:000032019326000077", cik == "0000320193"
```

---

## About Starling Quantitative

**[Starling Quantitative](https://starlingquant.com)** is the systematic U.S. equity research and capital allocation desk of Biwada LLC. Starling runs two layers of **100% deterministic, zero-LLM** U.S. equity scouts under a single non-parametric calibration and risk engine:

1. **The Proven Foundation (Point-in-Time Filing Scouts):** Rule-based scouts extracting factor-neutralized alpha from primary SEC, FDA, and patent disclosures across `3,607` survivorship-free Russell 3000 CIKs (`555` delisted retained; `+61.8%` OOS `2022–2026` unlevered vs. `SPY +54.3%`).
2. **The Experiment Layer (Darwinian Alt-Data Scouts):** A live survival-of-the-fittest ecosystem tracking ephemeral, differentiated alternative data feeds behind a One-Way Shadow/Canary Glass Wall—starting at `$0` in shadow and earning or losing capital automatically on live out-of-sample attribution.

### Open Research Monographs & Verification
- **Research Note RN-01:** [Point-in-Time Alternative Data Ingestion, Entity Resolution & Survivorship-Free Panel Construction](https://starlingquant.com/guides/point-in-time-alternative-data-and-survivorship-free-panels) ([PDF](https://starlingquant.com/papers/RN-01-Point-in-Time-Alternative-Data-Starling-Quantitative.pdf) | [DOI: 10.5281/zenodo.24222468](https://doi.org/10.5281/zenodo.24222468))
- **Research Note RN-02:** [Non-Parametric Signal Calibration, Orthogonal Pillar Pooling & One-Way Statutory Distress Vetoes](https://starlingquant.com/guides/non-parametric-signal-calibration-and-orthogonal-pillar-pooling) ([PDF](https://starlingquant.com/papers/RN-02-Non-Parametric-Signal-Calibration-Starling-Quantitative.pdf) | [DOI: 10.5281/zenodo.24222814](https://doi.org/10.5281/zenodo.24222814))
- **Research Note RN-03:** [Six-Factor Residual Attribution, Purged Walk-Forward Validation & Volatility-Parity Risk Governance](https://starlingquant.com/guides/multi-agent-quorum-and-systematic-factor-consensus) ([PDF](https://starlingquant.com/papers/RN-03-Six-Factor-Residual-Attribution-Starling-Quantitative.pdf) | [DOI: 10.5281/zenodo.24222816](https://doi.org/10.5281/zenodo.24222816))
- **Live Forward Attribution Scorecard:** [https://starlingquant.com/scorecard](https://starlingquant.com/scorecard)
- **Machine-Readable Specification:** [https://starlingquant.com/llms-full.txt](https://starlingquant.com/llms-full.txt)

*Disclosure: Starling Quantitative trades proprietary capital and conducts selective institutional research evaluation under mutual NDA. Nothing in this repository constitutes investment advice or an offer to solicit retail capital.*
