Valuein — SEC EDGAR fundamentals for analysts, quants, and AI agents

Survivorship-bias-free, point-in-time US fundamentals — streamed as Parquet, queried with DuckDB or natural language.

This repository is the public home and discovery hub for the Valuein data platform. It hosts the documentation, examples, notebooks, and the MCP registry manifest used by AI agents to find us. Source code for the SDK, MCP server, and data pipeline lives in dedicated repositories — this is the front door.

pip install valuein-sdk          # data for code
# or add this URL to any MCP-capable AI client:
# https://mcp.valuein.biz/mcp     # data for agents

What's in here

The data product

Survivorship-bias-free, point-in-time US fundamentals sourced directly from SEC EDGAR.

• 12M+ filings — 10-K, 10-Q, 8-K, 20-F, and amendments since 1994
• 105M+ standardized facts across 16,000+ active and delisted US entities
• 11,966 raw XBRL tags normalized to ~150 canonical standard_concept values (95% coverage)
• Cloud Parquet on Cloudflare R2 — stream with DuckDB; no database setup, no local downloads
• PIT-correct — every fact carries filing_date and millisecond-precision accepted_at
• Semantic core — every 10-K / 10-Q / 20-F's narrative sections (Risk Factors, MD&A, Business, Legal, Controls) chunked and indexed for natural-language search via the MCP server

Why it's different

Distribution channels

The same dataset, delivered four ways so it lands where you already work.

A single Stripe-issued token unlocks every channel at your tier — no per-channel billing.

Plans & access

Pricing and feature scope are mirrored from valuein.biz/pricing — the website is the source of truth and our checkout flow routes to the correct Stripe product.

Rate limits per tier (canonical at https://data.valuein.biz/v1/plans):

Quickstart (30 seconds, no token)

pip install valuein-sdk

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    print(client.me())               # {plan, status, email, createdAt}
    print(client.manifest())         # snapshot id, last_updated, tables
    print(client.tables())           # currently loaded tables

    df = client.run_query("""
        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.is_active = TRUE
        ORDER  BY r.name
        LIMIT  10
    """)
    print(df)

That's a real query against the live S&P 500 sample. Add a token only when you need full universe or full history:

echo 'VALUEIN_API_KEY="your_token_here"' >> .env

The same code now reads from your tier — no other changes.

Production pattern — context manager, typed errors, pre-built templates

from valuein_sdk import (
    ValueinClient,
    ValueinAuthError,
    ValueinPlanError,
    ValueinRateLimitError,
    ValueinAPIError,
)

with ValueinClient() as client:
    try:
        df = client.run_template(
            "fundamentals_by_ticker",
            ticker="AAPL",
            start_date="2020-01-01",
            end_date="2024-12-31",
            form_types=["10-K", "10-Q"],
            metrics=["TotalRevenue", "NetIncome", "OperatingCashFlow"],
        )
        print(df.head())
    except ValueinAuthError:
        print("Token missing or expired — set VALUEIN_API_KEY.")
    except ValueinPlanError:
        print("This query needs a higher plan — see valuein.biz/pricing.")
    except ValueinRateLimitError as e:
        print(f"Rate limited; retry in {e.retry_after}s.")
    except ValueinAPIError as e:
        print(f"Gateway error (HTTP {e.status_code}).")

The SDK ships 44 named SQL templates for the most common screens, ratios, and PIT backtests. List them:

from valuein_sdk import ValueinClient
with ValueinClient() as c:
    print(c.list_templates())

Reference: docs/QUERY_COOKBOOK.md (DuckDB recipes) · docs/data_catalog.md (canonical concepts) · PyPI README (SDK quickstart).

Recipes by role

Every link below points to a runnable script in examples/python/ (mirror notebook in examples/notebooks/). The Sample tier runs every example — no token, no signup.

Run any of them:

# Sample tier — works without a token
python examples/python/getting_started.py

# Paid tier
VALUEIN_API_KEY=xxx python examples/python/factor_screen.py

Data model

Full schema in docs/schema.json (machine-readable) and docs/data_catalog.md (canonical concept names).

Date columns — which to use when

For any cross-company backtest, always filter by filing_date <= trade_date. Filtering by report_date introduces look-ahead bias.

Three patterns that pay off in DuckDB

1. Start from references (one join for cross-company filters; membership is in index_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          -- current member
  AND  r.is_active     = TRUE
  AND  r.sector ILIKE '%technology%'

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:

SELECT
    MAX(CASE WHEN standard_concept = 'TotalRevenue'       THEN numeric_value END) AS revenue,
    MAX(CASE WHEN standard_concept = 'StockholdersEquity' THEN numeric_value END) AS equity
FROM   fact
WHERE  standard_concept IN ('TotalRevenue', 'StockholdersEquity')
GROUP  BY accession_id

Quarterly cash flows: use COALESCE(derived_quarterly_value, numeric_value) — Q2/Q3 10-Qs report YTD; this column isolates the single quarter. CAPEX sign varies by filer — always ABS(capex).

The full cookbook — 20 recipes, 8 anti-patterns, end-to-end factor screen — lives in docs/QUERY_COOKBOOK.md.

Canonical concept names

Query fact.standard_concept with canonical names like 'TotalRevenue', 'NetIncome', 'OperatingCashFlow', 'CAPEX', 'StockholdersEquity' — not raw XBRL tags ('Revenues', 'NetIncomeLoss', 'Assets'). The full list lives in docs/data_catalog.md and the machine-readable form is in docs/data_catalog.json.

MCP for AI agents

Valuein ships a remote Model Context Protocol server so any MCP-capable agent (Claude Desktop, Cursor, Codex, custom) can answer fundamentals questions without writing code.

• Endpoint: https://mcp.valuein.biz/mcp (Streamable HTTP, MCP spec 2025-11-25)
• Auth: Authorization: Bearer <your_api_token> — same token as the SDK and bulk-data API
• Manifest: server.json — published to registry.modelcontextprotocol.io as io.github.valuein/mcp-sec-edgar
• Reference: docs/MCP_TOOLS.md — every tool, every parameter, every tier gate

Tools

The server exposes 14 tools, plus 10 analyst SOP prompts (two flagship cross-persona briefs — equity_research_brief and screen_and_shortlist — plus eight specialised chains) and 2 data resources. Tier gating happens at the data layer — Sample / Free tokens see Sample / S&P 500 data; Pro and Enterprise see the full universe.

Discovery & schema

Fundamentals & ratios

Filings & lineage

Comparison & analytics

Bulk & semantic

Configure in Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "valuein": {
      "url": "https://mcp.valuein.biz/mcp",
      "headers": { "Authorization": "Bearer YOUR_VALUEIN_API_KEY" }
    }
  }
}

Same URL + Bearer token works for any MCP client that supports Streamable HTTP remotes — Cursor, Codex, your own LangGraph / CrewAI agent.

Examples in this repository

Every script and notebook works against the SDK published on PyPI. The Sample tier runs without a token; add VALUEIN_API_KEY to use a paid tier.

Python scripts (examples/python/)

Jupyter notebooks (examples/notebooks/)

Notebook	Open in Colab
Quickstart
Fundamental Analysis
PIT Backtest
Survivorship Bias
Factor Screen
Earnings Momentum
DCF Inputs

Documentation

Everything in docs/ is kept in sync with the production data and the SDK on PyPI.

Support & community

GitHub Issues is the primary support channel. Use the right template — it routes correctly and gets faster triage.

For private or contractual matters (DPAs, procurement, DDQs, enterprise SLAs): support@valuein.biz.

Contributions — examples, notebook improvements, documentation fixes, query recipes — are very welcome. See CONTRIBUTING.md for the workflow and CODE_OF_CONDUCT.md for community standards.

License & disclosure

Apache 2.0. See NOTICE for attribution.

This repository is provided for research and educational purposes. It is not investment advice. No warranty of fitness for any particular trading, investment, or regulatory purpose is implied.