valuein-sdk 0.2.0

Official Python SDK for the Valuein US Core Fundamentals dataset — SEC EDGAR financials via API.

Valuein 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) from 1990 to present. 20,000+ active and delisted entities. ~105M facts. Zero look-ahead bias.

---

Installation

# 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

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.

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

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

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/usage.py
• Schema: docs/schema.json
• Methodology: docs/METHODOLOGY.md
• Data Quality issues: Open a ticket

---

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

Apache-2.0 License — see LICENSE.