valuein

[![Valuein](https://www.valuein.biz/valuein/twitter-rounded.png)](https://valuein.biz)

[![PyPI version](https://img.shields.io/pypi/v/valuein-sdk?cacheSeconds=300)](https://pypi.org/project/valuein-sdk/)
[![PyPI downloads](https://img.shields.io/pypi/dm/valuein-sdk?label=pypi%20downloads&cacheSeconds=3600)](https://pypi.org/project/valuein-sdk/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/valuein-sdk/)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/valuein/valuein?style=flat&cacheSeconds=3600)](https://github.com/valuein/valuein/stargazers)
[![MCP Registry](https://img.shields.io/badge/MCP-registry.modelcontextprotocol.io-blue)](https://registry.modelcontextprotocol.io)
[![Docs](https://img.shields.io/badge/docs-valuein.biz-purple)](https://valuein.biz/developers/catalog)

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

> **Point-in-time, survivorship-free SEC fundamentals — built for AI agents, safe enough for institutions that fear AI.** Every number is born in a filing and carries a `fact_id`; the model never mints a digit. Streamed as Parquet, queried with DuckDB or natural language, reproducible run to run.

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](server.json) 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.

```bash
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

| You want to… | Go to |
|---|---|
| Try the SDK in 30 seconds without a token | [Quickstart](#quickstart-30-seconds-no-token) |
| See every channel we ship through | [Distribution channels](#distribution-channels) |
| Check pricing and what each plan unlocks | [Plans & access](#plans--access) |
| See why AI agents are first-class citizens here | [Built for AI agents](#built-for-ai-agents) |
| Connect an AI agent (Claude, Copilot, ChatGPT, Cursor…) | [MCP for AI agents](#mcp-for-ai-agents) |
| Set up the Workspace by role (analyst, PM, quant, creator) | [`docs/WORKSPACE_GUIDE.md`](docs/WORKSPACE_GUIDE.md) |
| Read the data model | [Data model](#data-model) |
| Find a quick recipe by role | [Recipes by role](#recipes-by-role) |
| Run end-to-end Python examples | [`examples/python/`](examples/python/) |
| Run interactive notebooks (Colab) | [`examples/notebooks/`](examples/notebooks/) |
| Read the methodology / SLA / compliance | [Documentation](#documentation) |
| Report a data error or request a feature | [Support & community](#support--community) |
| Contribute an example or notebook | [`CONTRIBUTING.md`](CONTRIBUTING.md) |

---

## 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, 40-F, and amendments since **1993**
- **111M+ standardized facts** across **19,000+** US public companies — including every bankruptcy, merger, and delisting since 1993
- **11,966 raw XBRL tags** normalized to **292 canonical `standard_concept`** values plus **164 materialized financial ratios** (FY + TTM); unmapped tags are exposed under `'Other'` rather than dropped
- **20 Parquet tables** — 14 core (fundamentals, ratios, valuations, index membership, daily OHLCV price history with adjusted close) + 6 smart-money tables (Institutional tier)
- **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`

### Why it's different

| Property | What it means for you |
|---|---|
| 🕒 **Point-in-time** | `filing_date <= trade_date` removes look-ahead bias. `accepted_at` gives intraday resolution for same-day signals. |
| ⚖️ **Survivorship-bias free** | Delisted, bankrupt, and acquired companies remain in every snapshot — your backtest sees the universe the market saw. |
| 📊 **Standardized concepts** | Both the raw XBRL tag (`fact.concept`) and the canonical name (`fact.standard_concept`) are on every row. No hidden mapping table. |
| 🔍 **CPA-verified catalog** | Every `standard_concept` carries a `review_confidence` — `1.0` once an accountant has signed off on its name, statement and rule (then it's locked; the pipeline only ever adds new concepts, never mutates a verified one), `0.7` while provisional. Filter `review_confidence >= 1.0` for the labels analysts, quants and AI models can agree on and train against. |
| 🚀 **DuckDB-native** | Millisecond analytics over remote Parquet via `httpfs`. Zero database provisioning. |
| 🔁 **Append-only restatements** | A `10-K/A` adds a new row — the original stays. Reconstruct the as-reported view of any historical date. |
| 🧾 **Measured, published accuracy** | Mathematical consistency checked against published, cited accounting identities — CI-gated, and re-derivable yourself with one DuckDB command. The current measured figure lives in [`docs/accuracy/baseline.json`](docs/accuracy/baseline.json). |
| 🔐 **One token, every channel** | The same Bearer token authenticates the SDK, MCP server, and bulk-data API. |

---

## Built for AI agents

Valuein is MCP-first and agent-agnostic: the same typed tool surface works in Claude, Copilot, ChatGPT, Perplexity, Gemini, Grok, Cursor, or your own LangGraph / CrewAI agent. The design goal is simple — **the model never mints a number**. Numbers are born in tools, carried as provenance-tagged facts, and the model is only allowed to arrange words around figures it was handed.

| Guarantee | How it's enforced |
|---|---|
| **Fact-level lineage** | Every figure a tool returns carries a `fact_id` and its source filing; `verify_fact_lineage` round-trips any `fact_id` back to the exact SEC filing URL in one call. |
| **Zero look-ahead** | Every time-series tool accepts `as_of_date` and reconstructs the information set as of that date — the same PIT discipline the Parquet layer enforces for backtests. |
| **Reproducible runs** | Deterministic, idempotent tools: same inputs, same output. No rolling windows, no hidden "latest". Agents can cache, retry, and replay; you can reproduce a run later. |
| **Agent-agnostic state** | Theses, claims, watchlists, alerts, and reports persist server-side across sessions *and across clients* — save a thesis from Claude today, list it from Cursor tomorrow. |
| **Human-on-the-loop (HOTL)** | Mutating and outward-facing tool actions go through a staged-action approval ledger: the agent proposes, a human approves, and the decision lands in an immutable audit entry. Read-only tools never stage. |
| **Governed managed runs** | Server-side managed agent runs execute at temperature 0 with a model allow-list and destructive-tool stripping — reproducible research, not improvisation. |
| **Graded track records** | Saved theses and claims are scored against subsequent fundamentals and prices; publishing builds a public, verifiable track record — your agent keeps score. |

The full tool reference is in [`docs/MCP_TOOLS.md`](docs/MCP_TOOLS.md); agent-facing runtime instructions are in [`AGENTS.md`](AGENTS.md).

---

## Distribution channels

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

| Channel | Audience | Endpoint / install |
|---|---|---|
| **Python SDK** | Quants, engineers, data scientists | `pip install valuein-sdk` · [PyPI](https://pypi.org/project/valuein-sdk/) |
| **MCP server** | AI agents (Claude, Copilot, ChatGPT, Cursor, custom) | `https://mcp.valuein.biz/mcp` · [server.json](server.json) |
| **Web dashboard** | Retail, executives, non-technical users | [valuein.biz](https://valuein.biz) |
| **Bulk data API** | B2B partners, fintech platforms | `https://data.valuein.biz` · [contact us](mailto:sales@valuein.biz) |

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](https://valuein.biz/pricing) — the website is the source of truth and our checkout flow routes to the correct Stripe product.

| Plan | Universe | History | Data freshness | Price | Get it |
|---|---|---|---|---|---|
| **Sample** | S&P 500 (~500 tickers) | 5-year window | Quarterly snapshots | **Free** · no signup | Just `pip install valuein-sdk` |
| **Free** | S&P 500 (~500 tickers) | 1993 – present | Daily | **Free** · register | [Register](https://valuein.biz/signup/free) |
| **Pro** | Full active + delisted US universe (19,000+ entities) — fundamentals dataset only | 15-year rolling (2011 → present) | 24h after SEC | **$49 / mo** · $490 / yr | [Subscribe](https://valuein.biz/checkout?tier=pro&billing=monthly) |
| **Institutional** | Same universe + **smart-money dataset** (insider transactions on Forms 3/4/5/144 + institutional ownership on Forms 13F/13D/13G) | 1993 – present (unlimited) | 4h priority + filing-event webhooks | **$499 / mo** · $4,790 / yr | [Subscribe](https://valuein.biz/checkout?tier=full&billing=monthly) |
| **Enterprise** | Negotiated · dedicated infrastructure · expanded redistribution scope | Custom | Real-time 8-K + zero-retention option | Talk to us | [sales@valuein.biz](mailto:sales@valuein.biz) |

Each tier removes a *different* buyer objection — Pro removes the universe + history limits on the fundamentals dataset; Institutional adds the smart-money dataset (insider transactions + institutional ownership), unlimited history back to 1993, filing-event webhooks, and a commercial redistribution license under a business-hours SLA; Enterprise adds dedicated infrastructure and bespoke contracts.

### Pay-per-call (MPP)

Autonomous AI agents that hit a rate or tier limit can pay per