💎 Valuein Python SDK: Frictionless Financial Data

A high-performance toolkit for querying point-in-time US fundamentals from SEC EDGAR, built for quants, analysts, and data engineers.

The Valuein SDK, is a complete infrastructure solution for consuming point-in-time accurate US Core financial fundamentals (facts) on your daily workflow. Whether you are building complex asynchronous Python pipelines or executing templated SQL, this library provides frictionless, zero-setup access to institutional-grade data.

The Data Engine

Powered by survivorship-bias-free data containing 12M+ filings and 120.5M+ facts from 10-Ks, 10-Qs, 8-Ks, 20-Fs, 40-Fs, and amendments across 19,000+ active and delisted US companies since 1993 (the SEC EDGAR electronic-filing floor).

Why use this toolkit?

⚡ Lightning-Fast Python SDK: Execute blazing-fast queries against remote Parquet files hosted on R2, powered entirely by DuckDB under the hood. No database setup, no massive local downloads.

🛠️ Plug-and-Play SQL Templates: Skip the boilerplate. Use our pre-built SQL templates to immediately extract insights, calculate intrinsic values, or model standardized financial statements.

📚 Comprehensive Context: Deep-dive documentation mapping out table schemas, primary keys, and field definitions to support your specific financial research use cases.

🚀 Why Valuein Data and SDK Library

Easy of use and intelligence.

🧠 What You Can Do With This Repository

⚡ Quickstart

1. Install Package

Pick the workflow you already use — both work, no extra setup:

# Option A — pip (universal, ships with Python)
python -m venv .venv && source .venv/bin/activate
pip install valuein-sdk

# Option B — uv (10–100× faster; install from https://docs.astral.sh/uv/)
uv venv && source .venv/bin/activate
uv pip install valuein-sdk

2. Backtest a factor — no token, no signup, one command

valuein backtest mom_12m --start 2021-01-01 --end 2025-12-31 --freq ME

Backtest — 'mom_12m' | long/short | top/bottom 5 quantiles | equal-weighted
  execution lag 1 trading day(s), costs 10.0 bps per unit traded, 11.78 rebalances/yr

NET OF COSTS
  Periods             40 @ 11.78/yr
  Annualized return   -2.04%
  Annualized vol      15.41%
  Sharpe              -0.06
  Max drawdown        -23.64%
  Hit rate            62.5%

  gross annualized   -0.87%   (cost drag 1.17%)
  mean IC            +0.0076   IC-IR 0.04
  mean turnover      50.4% one-way per rebalance
  universe return    +1.22% per period (equal-weight, same universe)

EXCLUSIONS
  dates used 40 of 52 — 12 skipped for thin coverage
  names scored 450/date (71% of universe had a usable signal)
  positions truncated by delisting: 0

That is a real run on the free tier, cold, in under 7 seconds — and it is a real answer: on the 500-name sample slice, 12-month momentum did not pay after costs. The point is that you found that out in one command instead of in two weeks, and that the assumptions are printed next to the number. A Sharpe ratio quoted without its execution lag and cost assumption is not a result.

The EXCLUSIONS block is there for the same reason. It tells you what the backtest could not use — thin dates, unscored names, positions truncated by a delisting — because a study that silently drops what it cannot handle reports the survivors' returns and calls them the strategy's.

Same thing from Python, plus the diagnostics:

from valuein_sdk import ValueinClient

with ValueinClient() as client:  # no API key needed
    result = client.factor_backtest(
        "mom_12m",
        start="2021-01-01",
        end="2025-12-31",
        freq="ME",
    )
    print(result.summary())
    print(result.mean_ic, result.ic_ir)  # signal quality
    print(result.quantile_summary())  # is it monotonic?
    result.equity_curve().plot()

Look-ahead and survivorship bias are closed by construction, not by convention: the universe comes from index-membership spells so delisted companies are present on the dates they were members, and every fundamental is filtered to accepted_at <= as_of, the moment the SEC actually published it. You cannot accidentally turn them off.

→ Full quickstart · Quant cookbook

Add a token at any time to widen the universe from 500 names to 19,000+ — the code above does not change.

🔑 2. Get Your API Token

🔐 3. Set Your API Token

# optional — sample tier works without a key
echo 'VALUEIN_API_KEY="your_token"' >> .env

▶️ 4. Production-ready code

The ValueinClient handles authentication, table discovery, and local caching in a high-performance DuckDB instance.

The Recommended Way For Production is the Context Manager block/pattern because it ensures that temporary files and database connections are closed automatically, even if your script crashes.

from valuein_sdk import ValueinClient, ValueinError

# Two-level try/except is intentional:
#   outer = init errors (auth, manifest fetch, gateway 503 at __enter__)
#   inner = per-query errors (rate-limit, plan denial, bad SQL, validation)

try:
    with ValueinClient() as client:
        try:
            # 1) Build & run a raw SQL query → pandas DataFrame
            sql = "SELECT COUNT(cik) FROM entity"
            result_df = client.run_query(sql)
            print(result_df)

            # 2) Run a named SQL template with kwargs (the SDK quotes safely)
            df = client.run_template(
                "fundamentals_by_ticker",
                ticker="AAPL",
                start_date="2020-01-01",
                end_date="2024-01-01",
                form_types=["10-K", "10-Q"],
                metrics=["TotalRevenue", "NetIncome", "OperatingCashFlow"],
            )
            print(df)
        except ValueinError as ve:
            print(f"Query failed: {ve}")
except Exception as e:
    print(f"Initialization failed: {e}")

🧰 API Reference

Everything below is importable from the top-level package (from valuein_sdk import ...) and fully type-hinted with help()-ready docstrings — so an LLM reading the signatures can call it correctly on the first try.

Company identifiers: ticker OR CIK, anywhere you see ticker/tickers. A ticker ("AAPL", "BRK.B") resolves through references, preferring active listings. A CIK ("0000714154", "714154", or the int 714154 — any of the three) is used directly — it never touches references, so it resolves even for a delisted/inactive company whose ticker was retired or later recycled by an unrelated issuer (DEC used to be Digital Equipment; today it's Diversified Energy). Mixed lists work: client.prices(["AAPL", "0000714154", 320193]). Call client.resolve(identifiers) to see exactly what each one matched (symbol, name, is_active, matched_by) before it feeds a backtest.

ValueinClient(as_of=None, api_key=None, gateway_url=None, tables=None, config=None)

The on-disk cache

Downloaded Parquet is cached under ~/.cache/valuein-sdk (override with ValueinConfig(cache_dir=...)) so a second process starts warm instead of re-downloading. Two things keep it honest, and both are automatic:

• Hits are revalidated. Before a cached object is served, the SDK checks its ETag against the published one — a single body-free HEAD per object per session. Most publishes land under a new snapshot_YYYYMMDD prefix, which a cache addressed by snapshot name already sees; but some do not — a same-day re-publish and a targeted fix both rewrite objects inside the live prefix. Those are usually bug fixes, and a name-addressed cache would hide exactly the correction you were waiting for. The check fails open: if the gateway cannot be reached, you get the cached bytes rather than an error. Turn it off for a deliberately frozen read with ValueinConfig(cache_revalidate=False).
• Superseded snapshots are pruned when a client starts, so the cache does not accumulate a copy of every dataset you have ever read.

You should not need to clear it. If you want to anyway:

valuein cache stats                 # where it is, how big it is
valuein cache clear                 # all of it
valuein cache clear --table fact    # just one table

client.clear_cache(table="fact")  # {'entries': 1, 'bytes': 189384807}
client.cache_info()  # root, size, snapshot, revalidate policy

The CLI commands talk to no gateway and need no API key — they are meant to work on the plane, on an expired token, and during an outage.

Alpha framework

from valuein_sdk import AlphaEngine, ROE, GROSS_MARGIN, CURRENT_RATIO

with ValueinClient() as client:
    result = (
        AlphaEngine(client)
        .add_factors(ROE, GROSS_MARGIN, CURRENT_RATIO)
        .compute(as_of="2024-01-01")
    )
    top = result.rank().combine()  # composite cross-sectional score
    print(top.head())

Built-ins: ROE, GROSS_MARGIN, OPERATING_MARGIN, NET_PROFIT_MARGIN, REVENUE_GROWTH_YOY, FCF_TO_ASSETS, DEBT_TO_EQUITY, ASSET_TURNOVER, CURRENT_RATIO, PIOTROSKI_F_SCORE (all in BUILTIN_FACTORS). Define your own with AlphaFactor.

One token, four channels

Your Stripe-issued Bearer token unlocks every Valuein surface at your tier — no per-channel billing:

The SDK is the Muscle (compute); the MCP server is the Nervous System (reasoning). The generate_* methods above are the bridge — they let SDK power users reach the MCP's document-generation tools without writing a JSON-RPC client.

🗂️ Data Schema

The authoritative schema is embedded in each tier's R2 manifest.json (written by data-pipeline/run_exports.py). The SDK fetches it at init and exposes the active version via client.get_schema(table) — there is no bundled schema file in this package. Use print(client.get_schema("fact")) to inspect column types live.

Current snapshot: schema v3.0.0, 22 tables (14 core on every tier + 6 smart-money and 2 Form ADV tables on the Institutional tier). The exact column list for any table is live in the manifest — run client.get_schema("fact"). Intrinsic value has no precomputed table — the valuation table was removed 2026-09-14; compute it on demand via the MCP compute_dcf tool with your own WACC / terminal growth / horizon assumptions. Parameter-free price multiples (pe_ratio, pb_ratio, ev_ebitda, dividend_yield, market_cap, graham_number, ncav_per_share) still ship precomputed under ratio.category = 'valuation'.

🔗 Key Joins

references.cik                  →  entity.cik  (references is the fast entry point)
security.entity_id              →  entity.cik
filing.entity_id                →  entity.cik
fact.entity_id                  →  entity.cik
fact.accession_id               →  filing.accession_id
index_membership.cik            →  entity.cik   (same column name on both sides
                                                 since migration 0015 — JOIN as
                                                 references.cik = im.cik)

🎯 Survivorship-free PIT universe (the canonical backtest pattern)

-- All SP500 members on a historical as_of_date, resolved to active ticker.
-- index_membership keys on `cik` (since pipeline migration 0015) — same column
-- name as references.cik / entity.cik, so the join read straight across.
SELECT m.cik, s.id AS security_id, s.symbol AS ticker_at_date,
       e.name AS company_name, m.effective_date, m.removal_date, m.confidence
FROM index_membership m
JOIN entity e ON e.cik = m.cik
LEFT JOIN security s ON s.entity_id = m.cik
    AND s.is_primary_ticker = TRUE
    AND $as_of_date >= s.valid_from
    AND $as_of_date <  COALESCE(s.valid_to, '9999-12-31'::DATE)
WHERE m.index_name = 'SP500'
  AND $as_of_date >= m.effective_date
  AND $as_of_date <  COALESCE(m.removal_date, '9999-12-31'::DATE);

LEFT JOIN security so delisted companies still surface (ticker_at_date = NULL). is_primary_ticker = TRUE pins multi-share-class issuers to one row per CIK — universe count stays at ~500 even when BRK-A and BRK-B both exist in security. [) semantics — a company removed on 2017-06-19 is NOT a member ON 2017-06-19.

⚡ DuckDB Query Patterns

Three patterns that eliminate redundant joins and scans on every cross-company query:

1. references replaces the entity + security join; index_membership stays separate

-- Filter current S&P 500 tech companies (membership lives in index_membership).
-- The previous references.is_sp500 flag was dropped 2026-05-02 — both
-- snapshot-only and single-index, two footguns avoided by JOIN-on-membership.
SELECT r.symbol, r.name, r.sector
FROM   "references" r
JOIN   index_membership im ON im.cik = r.cik
WHERE  im.index_name   = 'SP500'
  AND  im.removal_date IS NULL
  AND  r.sector ILIKE '%technology%'
  AND  r.is_active     = TRUE

2. LATERAL for the latest filing per company

JOIN LATERAL (
  SELECT accession_id, filing_date
  FROM   filing
  WHERE  entity_id = r.cik AND form_type = '10-K'
  ORDER  BY filing_date DESC
  LIMIT  1
) f ON true

3. Pivot multiple concepts in one fact scan

-- Debt + equity in one pass — no self-join
SELECT
  MAX(CASE WHEN standard_concept = 'LongTermDebt'       THEN numeric_value END) AS debt,
  MAX(CASE WHEN standard_concept = 'StockholdersEquity' THEN numeric_value END) AS equity
FROM fact WHERE standard_concept IN ('LongTermDebt', 'StockholdersEquity')
GROUP BY accession_id

For quarterly cash flow metrics, use COALESCE(derived_quarterly_value, numeric_value) — Q2/Q3 10-Qs report YTD; this column isolates the single quarter.

See valuein_sdk/queries/SQL_CHEATSHEET.md for 8 complete patterns including FCF screens, PIT backtesting, and restatement auditing.

🏷️ Standard Concept Names

📅 Date Columns Reference

🧩 Template Categories

57 templates ship in valuein_sdk/queries/, auto-discovered by filename. Run any of them with client.run_template("<name>", ...):

See valuein_sdk/queries/SQL_CHEATSHEET.md for the full reference with copy-paste DuckDB patterns.

📚 Documentation

🐍 Python Examples

Standalone Python scripts and ten Jupyter notebooks, designed to go from install to insight in under 3 minutes.

Ticker lookup example

Run any SQL against the data lake. No downloads. No local database. DuckDB executes your queries in-process.

from valuein_sdk import ValueinClient

client = ValueinClient(tables=["entity", "security"])
# This client only fetch these 2 tables, making it faster!

df = client.run_query("""
    SELECT e.cik, e.name, e.sector, e.status,
           s.symbol, s.exchange
    FROM   security s
    JOIN   entity   e ON s.entity_id = e.cik
    WHERE  s.symbol = 'AAPL' AND s.is_active = TRUE
""")
print(df)

You are now querying SEC financial statements directly from the cloud.

Python scripts (examples/python/)

Jupyter notebooks (notebooks/)

Notebook	Open in Colab
01_quickstart
02_dcf_valuation
03_piotroski_screen
04_earnings_quality
05_factor_backtest
06_sector_comparison
07_restatement_alpha
08_capital_allocation
09_filing_delay
10_survivorship_demo

🛡️ Error Handling

from valuein_sdk import (
    ValueinAuthError,  # HTTP 401/403 — invalid or expired token
    ValueinPlanError,  # HTTP 403 — endpoint requires a higher plan
    ValueinNotFoundError,  # HTTP 404 — no table found
    ValueinRateLimitError,  # HTTP 429 — includes .retry_after (seconds)
    ValueinAPIError,  # HTTP 5xx — includes .status_code
    ValueinClient,
)

client = None
try:
    client = ValueinClient()
    df = client.run_query("SELECT * FROM fact LIMIT 1000000")
except ValueinAuthError:
    print("Check your VALUEIN_API_KEY. It might be expired or invalid.")
except ValueinPlanError:
    print("This requires a higher-tier plan. Upgrade at valuein.biz.")
except ValueinRateLimitError as e:
    print(f"Slow down! Retry allowed in {e.retry_after}s.")
except ValueinNotFoundError as e:
    print(f"That table or endpoint doesn't exist: {e}")
except ConnectionError as e:
    print(f"Physical network issue: {e}")
except ValueinAPIError as e:
    print(f"The Gateway is having a bad day (Status {e.status_code}).")
except Exception as e:
    print(f"Non-SDK error (Python/Logic): {e}")
finally:
    # Always close manually if not using a context manager and if a client was created.
    if client is not None:
        client.close()

📮 Reporting a Data Issue

Found a stale figure, a bad citation, or a rough edge? report_issue() files it straight to the Valuein team over the MCP submit_feedback tool — no API token required, so it works even in sample mode. Pass ticker and/or fact_id when you have them so the report is checkable against the source filing.

from valuein_sdk import FeedbackError, ValueinClient

client = ValueinClient()  # works even with no API key
try:
    receipt = client.report_issue(
        "get_financial_ratios returns a stale P/E for AAPL",
        category="data_quality",  # "bug" | "feature_request" | "experience" | "data_quality" | "other"
        ticker="AAPL",
        fact_id="3f9c1a2b...",
        expected_value="24.1",
    )
    print(receipt.feedback_id, receipt.status)  # e.g. "fb_9f2c...", "open"
except FeedbackError as e:
    print(f"Valuein rejected the report: {e}")

🔬 Research & Quality Proofs

The ten notebooks double as runnable due-diligence proofs — PIT correctness, survivorship-bias quantification, restatement alpha, and balance-sheet identity checks — all against live data. Install the research extras to run them locally:

# pip
pip install "valuein-sdk[research]"
# uv (dev workflow)
uv sync --group research

For institutional due-diligence material (methodology, compliance/DDQ, SLA, and the full reproducible research suite) see the open-source hub at github.com/valuein/valuein.

🤝 Contributing

We welcome contributions including SQL templates, notebooks, scripts, research modules, and documentation improvements.

See CONTRIBUTING.md for code standards, naming conventions, and the PR process.

📄 License

Apache-2.0 License — see LICENSE.

Disclosure: This repository is for research and educational purposes only and does not constitute financial advice.