valuein-sdk 0.3.1

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

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

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

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:

# 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

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

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:

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	Install, authenticate, first query
backtest_pit.ipynb	Point-in-Time backtest walkthrough
screening.ipynb	Fundamental factor screening across the S&P 500
bankruptcy_analysis.ipynb	Altman Z-score and distress signals

---

Documentation

• Methodology: docs/METHODOLOGY.md — PIT architecture, standardization logic, restatement handling
• Schema: docs/schema.json — Full column-level data dictionary
• SLA: docs/SLA.md — Uptime, data freshness, support response times
• Compliance / DDQ: docs/COMPLIANCE_AND_DDQ.md — MNPI policy, PIT integrity, security
• Data issues: Open a ticket

---

For research and educational purposes only. Not financial advice.

Apache-2.0 License — see LICENSE.