Metadata-Version: 2.4
Name: valuein-sdk
Version: 0.2.0
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
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: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
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

# Valuein Financial Data Essentials (FDE)

[![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)]()
[![License](https://img.shields.io/badge/license-Apache%202.0-green)]()

**Institutional-grade SEC fundamental data. Point-in-Time accurate, survivorship-bias free.**

Standardized US Core Fundamentals (10-K, 10-Q, 8-K) from 1990 to present.
20,000+ active and delisted entities. ~105M facts. Zero look-ahead bias.

---

## Installation

```bash
# Set your API key (get one at valuein.biz)
export VALUEIN_API_KEY="your_api_key"

# Install
uv add valuein-sdk
# or: pip install valuein-sdk
```

## Quickstart

```python
from valuein_sdk import ValueinClient

client = ValueinClient()  # reads VALUEIN_API_KEY from env

# Run any SQL against the data warehouse
df = client.query("""
    SELECT s.symbol, f.report_date, fa.standard_concept, fa.numeric_value
    FROM security s
    JOIN filing f  ON s.entity_id = f.entity_id
    JOIN fact fa   ON f.accession_id = fa.accession_id
    WHERE s.symbol = 'AAPL' AND s.is_active = TRUE
    ORDER BY f.report_date DESC
    LIMIT 20
""")
print(df)
```

That's it. No downloads — DuckDB streams only the rows your query needs from Cloudflare R2.

---

## Core Concepts

### Point-in-Time (PIT) Backtesting

Every fact has a `filing_date` (when the SEC received the filing) and a `report_date` (the fiscal period end). **Always filter by `filing_date <= your_trade_date`** to avoid look-ahead bias.

```python
# Correct PIT backtest — only use data the market had on 2024-01-15
df = client.query("""
    SELECT fa.standard_concept, fa.numeric_value
    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) |
| `security` | Ticker symbols with date ranges (`valid_from`, `valid_to`, `is_active`) |
| `filing` | SEC filing metadata (form type, filing date, report date) |
| `fact` | Standardized financial facts (standard_concept, numeric_value, unit) |
| `taxonomy_guide` | Human-readable definitions of all standard concepts |
| `index_membership` | Historical S&P 500 and other index membership |

### Pre-built SQL Templates

40+ ready-to-run templates for common quant workflows:

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

See `valuein_sdk/queries/` for the full list (Altman Z-score, DuPont, TTM, FCF, and more).

---

## API Reference

```python
client = ValueinClient(api_key="...", gateway_url="...")  # gateway_url optional

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 (current data date)
```

---

## Resources

- **Examples:** [`examples/getting_started.py`](examples/getting_started.py), [`examples/usage.py`](examples/usage.py)
- **Schema:** [`docs/schema.json`](docs/schema.json)
- **Methodology:** [`docs/METHODOLOGY.md`](docs/METHODOLOGY.md)
- **Data Quality issues:** [Open a ticket](https://github.com/valuein/quants/issues/new?template=01_data_quality_report.md)

---

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

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