Metadata-Version: 2.4
Name: valuein-sdk
Version: 0.3.1
Summary: Official Python SDK for the Valuein US Core Fundamentals dataset — SEC EDGAR financials via API.
Project-URL: Homepage, https://valuein.biz
Project-URL: Documentation, https://valuein.biz/docs
Project-URL: Repository, https://github.com/valuein/quants
Project-URL: Bug Tracker, https://github.com/valuein/quants/issues
Project-URL: Changelog, https://github.com/valuein/quants/blob/main/CHANGELOG.md
Author-email: Valuein <support@valuein.biz>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: EDGAR,SEC,backtesting,duckdb,finance,fundamentals,parquet,quant
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: duckdb>=1.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: research
Requires-Dist: ipykernel>=6.29.0; extra == 'research'
Requires-Dist: jupytext>=1.16.0; extra == 'research'
Requires-Dist: matplotlib>=3.8.0; extra == 'research'
Requires-Dist: numpy>=1.26.0; extra == 'research'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest>=9.0.0; extra == 'test'
Description-Content-Type: text/markdown

![](https://valuein.biz/valuein/linkedin-rounded.png)

[![PyPI version](https://img.shields.io/pypi/v/valuein-sdk)](https://pypi.org/project/valuein-sdk/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/valuein-sdk/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green)](https://github.com/valuein/quants/blob/main/LICENSE)
[![CI](https://github.com/valuein/quants/actions/workflows/publish.yml/badge.svg)](https://github.com/valuein/quants/actions/workflows/publish.yml)

# Financial Data Essentials (FDE)
**Institutional-grade SEC fundamental data. Point-in-Time accurate, survivorship-bias free.**

Standardized US Core Fundamentals (10-K, 10-Q, 8-K) sourced directly from SEC EDGAR.
20,000+ active and delisted entities. ~105M standardized facts. Coverage from 1990 to present.

---

## Quickstart

```bash
pip install valuein-sdk
export VALUEIN_API_KEY="your_key"   # get one at valuein.biz
```

```python
from valuein_sdk import ValueinClient

client = ValueinClient()
df = client.query("SELECT symbol, report_date, standard_concept, numeric_value FROM fact JOIN filing USING (accession_id) JOIN security USING (entity_id) WHERE symbol = 'AAPL' ORDER BY report_date DESC LIMIT 10")
print(df)
```

No downloads. DuckDB streams only the rows your query needs directly from Cloudflare R2.

---

## Why Valuein FDE

| Feature | Detail |
|---|---|
| **Point-in-Time (PIT)** | Every fact carries `filing_date` — the date the SEC received the filing. Filter by `filing_date <= trade_date` to eliminate look-ahead bias. |
| **Survivorship-bias free** | Includes all 20,000+ entities ever listed, including delisted, bankrupt, and acquired companies. |
| **Standardized concepts** | 15,000+ raw XBRL tags mapped to ~150 consistent metrics via waterfall logic. Restatements appended, never overwritten. |
| **Zero-copy DuckDB** | The SDK registers an authenticated DuckDB HTTP secret. Your SQL runs instantly — no local caching required. |
| **40+ SQL templates** | Ready-to-run queries for Altman Z-score, DuPont decomposition, TTM, FCF, sector screening, and more. |

---

## Point-in-Time Backtesting

Always gate on `filing_date`, not `report_date`, to avoid trading on data the market did not yet have:

```python
# Only use information available to the market on 2024-01-15
df = client.query("""
    SELECT fa.standard_concept, fa.numeric_value, f.filing_date
    FROM fact fa
    JOIN filing f ON fa.accession_id = f.accession_id
    JOIN security s ON f.entity_id = s.entity_id
    WHERE s.symbol = 'MSFT'
      AND f.filing_date <= '2024-01-15'   -- PIT gate
    ORDER BY f.report_date DESC
    LIMIT 10
""")
```

---

## Available Tables

| Table | Description |
|---|---|
| `entity` | Legal company entities — CIK, name, sector, SIC code |
| `security` | Ticker symbols with date ranges (`valid_from`, `valid_to`, `is_active`) |
| `filing` | SEC filing metadata — form type, `filing_date`, `report_date`, accession number |
| `fact` | Standardized financial facts — `standard_concept`, `numeric_value`, `unit` |
| `taxonomy_guide` | Human-readable definitions for all 150+ standard concepts |
| `index_membership` | Historical S&P 500 and other index constituent records |

---

## Pre-built SQL Templates

```python
df = client.run_template(
    "01_fundamentals_by_ticker",
    ticker="NVDA",
    form_types=["10-K"],
    metrics=["Revenues", "NetIncomeLoss", "OperatingIncomeLoss"],
    start_date="2020-01-01",
    end_date="2026-01-01",
)
```

40+ templates in `valuein_sdk/queries/` — Altman Z-score, DuPont, TTM, FCF, sector screening, bankruptcy signals, and more.

---

## API Reference

```python
client = ValueinClient(api_key="...", gateway_url="...")  # gateway_url for local dev only

client.query(sql)                    # Run arbitrary DuckDB SQL → DataFrame
client.get(table)                    # Download full table → DataFrame
client.run_template(name, **kwargs)  # Run a named .sql template → DataFrame
client.tables()                      # List available table names
client.me()                          # Token details: plan, status, email
client.manifest()                    # Snapshot metadata: snapshot ID, last_updated
```

**Exception hierarchy:**

```python
from valuein_sdk import (
    ValueinError,         # base class
    ValueinAuthError,     # HTTP 401/403 — invalid or revoked token
    ValueinPlanError,     # HTTP 403 — resource requires Full Dataset plan
    ValueinNotFoundError, # HTTP 404
    ValueinRateLimitError,# HTTP 429 — includes .retry_after seconds
    ValueinAPIError,      # HTTP 5xx or unexpected status
)
```

---

## Examples

| Notebook | Description |
|---|---|
| [`quickstart.ipynb`](examples/quickstart.ipynb) | Install, authenticate, first query [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/valuein/quants/blob/main/examples/quickstart.ipynb) |
| [`backtest_pit.ipynb`](examples/backtest_pit.ipynb) | Point-in-Time backtest walkthrough [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/valuein/quants/blob/main/examples/backtest_pit.ipynb) |
| [`screening.ipynb`](examples/screening.ipynb) | Fundamental factor screening across the S&P 500 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/valuein/quants/blob/main/examples/screening.ipynb) |
| [`bankruptcy_analysis.ipynb`](examples/bankruptcy_analysis.ipynb) | Altman Z-score and distress signals [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/valuein/quants/blob/main/examples/bankruptcy_analysis.ipynb) |

---

## Documentation

- **Methodology:** [`docs/METHODOLOGY.md`](docs/METHODOLOGY.md) — PIT architecture, standardization logic, restatement handling
- **Schema:** [`docs/schema.json`](docs/schema.json) — Full column-level data dictionary
- **SLA:** [`docs/SLA.md`](docs/SLA.md) — Uptime, data freshness, support response times
- **Compliance / DDQ:** [`docs/COMPLIANCE_AND_DDQ.md`](docs/COMPLIANCE_AND_DDQ.md) — MNPI policy, PIT integrity, security
- **Data issues:** [Open a ticket](https://github.com/valuein/quants/issues/new?template=01_data_quality_report.md)

---

> For research and educational purposes only. Not financial advice.

Apache-2.0 License — see [LICENSE](LICENSE).
