valuein-sdk 3.2.0__tar.gz → 3.3.1__tar.gz

{valuein_sdk-3.2.0 → valuein_sdk-3.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: valuein-sdk
-Version: 3.2.0
+Version: 3.3.1
 Summary: Official Python SDK for the Valuein US Core Fundamentals dataset — SEC EDGAR financials via API.
 Project-URL: Homepage, https://valuein.biz
 Project-URL: Documentation, https://valuein.biz/docs
@@ -85,7 +85,7 @@ Powered by survivorship-bias-free data containing 12M+ filings and 108M+ facts f
 |---------------------------------------|-----------------------------------------------------------|
 | 🕒 **<span title="Provides historical snapshots for accurate backtesting">Point‑in‑Time Data</span>** | Eliminate look‑ahead bias in backtests |
 | ⚖️ **<span title="Includes companies that went bankrupt, delisted, or were acquired">Survivorship‑Bias Free</span>** | Includes bankrupt, delisted, and acquired firms |
-| 📊 **<span title="Maps 15k+ raw XBRL tags to ~150 standard financial concepts">Standardized Concepts</span>** | 15k+ XBRL tags mapped to ~150 canonical financial concepts |
+| 📊 **<span title="Maps 15k+ raw XBRL tags to 292 standard financial concepts">Standardized Concepts</span>** | 15k+ XBRL tags mapped to 292 canonical financial concepts |
 | 🚀 **<span title="High-speed in-memory SQL engine using DuckDB">DuckDB SQL Engine</span>** | Millisecond analytics directly in Python |
 | ☁️ **<span title="Stream Parquet data from cloud storage without downloading locally">Cloud Parquet Streaming</span>** | No local data downloads required |
 | 🧩 **<span title="Ready-to-use financial templates for backtesting and signals">Financial Templates</span>** | Production‑ready investment signals |
@@ -210,7 +210,7 @@ except Exception as e:
 | **filing**         | Filing metadata since 1994. `is_xbrl_numeric` flags filings whose XBRL exhibit carries numeric facts; `superseded_by` chains the amendment lineage; `core_type` strips `/A` for form-family filtering. | 12M+    |
 | **fact**           | Financial statement facts with Bloomberg-style restatement columns (`value_current`, `value_as_filed`, `first_filed_at`, `restated`) and PIT semantics via `accepted_at`. | 105M+   |
 | **valuation**      | Pre-computed intrinsic values per (entity_id, valuation_date, model_type). Multiple `model_type` rows coexist: `dcf` / `dcf_fcf` / `ddm`. | ~500K   |
-| **taxonomy_guide** | Definitions for every `standard_concept` in `fact`. | ~150 |
+| **taxonomy_guide** | Definitions for every `standard_concept` in `fact`. | 292 |
 | **index_membership** | Historical index constituents (SP500, NASDAQ100, RUSSELL3000, WILSHIRE5000). Keyed on **`cik`** (since pipeline migration 0015 — same column name as `references.cik`). `effective_date` / `removal_date` use `[)` interval semantics; carries `announcement_date`, `removal_reason`, `successor_cik`, `source`, `confidence`. Survivorship-free backtests. | ~50K |
 | **filing_text** 🆕 | 10-K / 10-Q / 20-F narrative chunks (Risk Factors, MD&A, …) extracted from iXBRL TextBlocks. Source of the Vectorize index powering `search_filing_text` on MCP. PIT-correct via `accepted_at`. See [Semantic Search](#semantic-search-table-filing_text). | growing |
 | **factor_scores** | Cross-sectional factor scores + percentile ranks (10 factors + composite_rank) from latest two 10-Ks | 16K+    |

{valuein_sdk-3.2.0 → valuein_sdk-3.3.1}/README.md

@@ -33,7 +33,7 @@ Powered by survivorship-bias-free data containing 12M+ filings and 108M+ facts f
 |---------------------------------------|-----------------------------------------------------------|
 | 🕒 **<span title="Provides historical snapshots for accurate backtesting">Point‑in‑Time Data</span>** | Eliminate look‑ahead bias in backtests |
 | ⚖️ **<span title="Includes companies that went bankrupt, delisted, or were acquired">Survivorship‑Bias Free</span>** | Includes bankrupt, delisted, and acquired firms |
-| 📊 **<span title="Maps 15k+ raw XBRL tags to ~150 standard financial concepts">Standardized Concepts</span>** | 15k+ XBRL tags mapped to ~150 canonical financial concepts |
+| 📊 **<span title="Maps 15k+ raw XBRL tags to 292 standard financial concepts">Standardized Concepts</span>** | 15k+ XBRL tags mapped to 292 canonical financial concepts |
 | 🚀 **<span title="High-speed in-memory SQL engine using DuckDB">DuckDB SQL Engine</span>** | Millisecond analytics directly in Python |
 | ☁️ **<span title="Stream Parquet data from cloud storage without downloading locally">Cloud Parquet Streaming</span>** | No local data downloads required |
 | 🧩 **<span title="Ready-to-use financial templates for backtesting and signals">Financial Templates</span>** | Production‑ready investment signals |
@@ -158,7 +158,7 @@ except Exception as e:
 | **filing**         | Filing metadata since 1994. `is_xbrl_numeric` flags filings whose XBRL exhibit carries numeric facts; `superseded_by` chains the amendment lineage; `core_type` strips `/A` for form-family filtering. | 12M+    |
 | **fact**           | Financial statement facts with Bloomberg-style restatement columns (`value_current`, `value_as_filed`, `first_filed_at`, `restated`) and PIT semantics via `accepted_at`. | 105M+   |
 | **valuation**      | Pre-computed intrinsic values per (entity_id, valuation_date, model_type). Multiple `model_type` rows coexist: `dcf` / `dcf_fcf` / `ddm`. | ~500K   |
-| **taxonomy_guide** | Definitions for every `standard_concept` in `fact`. | ~150 |
+| **taxonomy_guide** | Definitions for every `standard_concept` in `fact`. | 292 |
 | **index_membership** | Historical index constituents (SP500, NASDAQ100, RUSSELL3000, WILSHIRE5000). Keyed on **`cik`** (since pipeline migration 0015 — same column name as `references.cik`). `effective_date` / `removal_date` use `[)` interval semantics; carries `announcement_date`, `removal_reason`, `successor_cik`, `source`, `confidence`. Survivorship-free backtests. | ~50K |
 | **filing_text** 🆕 | 10-K / 10-Q / 20-F narrative chunks (Risk Factors, MD&A, …) extracted from iXBRL TextBlocks. Source of the Vectorize index powering `search_filing_text` on MCP. PIT-correct via `accepted_at`. See [Semantic Search](#semantic-search-table-filing_text). | growing |
 | **factor_scores** | Cross-sectional factor scores + percentile ranks (10 factors + composite_rank) from latest two 10-Ks | 16K+    |

{valuein_sdk-3.2.0 → valuein_sdk-3.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name            = "valuein-sdk"
-version         = "3.2.0"
+version         = "3.3.1"
 description     = "Official Python SDK for the Valuein US Core Fundamentals dataset — SEC EDGAR financials via API."
 readme          = "README.md"
 requires-python = ">=3.10"

{valuein_sdk-3.2.0 → valuein_sdk-3.3.1}/valuein_sdk/client.py

@@ -196,6 +196,13 @@ _KNOWN_TABLES = frozenset(
         "filing",
         "fact",
         "taxonomy_guide",
+        # Curated gold-standard concept catalog (~292 rows) — the dictionary for
+        # fact.standard_concept (level, statement_type, definition, Bloomberg/
+        # FactSet equivalents). Distinct from taxonomy_guide, which is the raw
+        # SEC us-gaap tag reference for fact.concept. Exported as of pipeline
+        # schema 2.10.0; resolved from the manifest at runtime, listed here so
+        # the offline fallback (manifest fetch failed) still admits it.
+        "standard_concept",
         "index_membership",
         "ratio",
         "factor_scores",
@@ -214,7 +221,7 @@ _KNOWN_TABLES = frozenset(
         "insider_party",
         "insider_transaction",
         "institutional_holding",
-        "beneficial_ownership",
+        "insider_ownership",
         # Wide-format financial statement tables (v2.5.0).  Denormalized pivots
         # of `fact` keyed by (cik, period_end, fiscal_period) with one column
         # per canonical concept — let DuckDB skip the CASE-WHEN pivot pattern
@@ -247,7 +254,7 @@ _PIT_TABLES = frozenset(
         "filing_text",
         "insider_transaction",
         "institutional_holding",
-        "beneficial_ownership",
+        "insider_ownership",
     }
 )
 
@@ -468,8 +475,14 @@ class ValueinClient:
         # available (authenticated plans only).  Falls back to _BUNDLED_CONCEPTS
         # for sample/offline mode via the _concept_set property.
         concepts_from_manifest = self._manifest_data.get("standard_concepts")
+        # manifest standard_concepts may be a list of names (legacy) or a list of
+        # concept-metadata dicts (current). Normalise to a name set either way.
         self._valid_concepts: frozenset[str] | None = (
-            frozenset(concepts_from_manifest) if concepts_from_manifest else None
+            frozenset(
+                c["standard_concept"] if isinstance(c, dict) else c for c in concepts_from_manifest
+            )
+            if concepts_from_manifest
+            else None
         )
 
         if self._tables:
@@ -1343,10 +1356,10 @@ class ValueinClient:
         """Return rows from the ``factor_scores`` table.
 
         ``factor_scores`` ships in parquet schema 2.3.0+ and pre-computes
-        10 cross-sectional factors (roe, gross_margin, operating_margin,
+        cross-sectional factor columns (roe, gross_margin, operating_margin,
         net_profit_margin, revenue_growth_yoy, fcf_to_assets, debt_to_equity,
         asset_turnover, current_ratio, piotroski_f_score) plus a percentile
-        ``*_rank`` for each (0.0–1.0 where 1.0 = best) and an equal-weight
+        ``*_rank`` for each (0.0–1.0 where 1.0 = best) and a proprietary
         ``composite_rank``.
 
         Args:
@@ -1396,10 +1409,9 @@ class ValueinClient:
         """Return rows from the ``earnings_signals`` table.
 
         ``earnings_signals`` ships in parquet schema 2.3.0+ and pre-computes
-        TTM EPS trend (``eps_trend_est`` = trailing 4-quarter average of
-        EPSDiluted), the most recent ``eps_actual``, the surprise pct
-        ``eps_surprise_pct = (actual - trend_est) / |trend_est|``, and
-        ``revenue_yoy_pct``.
+        a proprietary TTM EPS trend estimate (``eps_trend_est``), the most
+        recent ``eps_actual``, the surprise pct ``eps_surprise_pct`` (actual
+        EPS measured against the trend estimate), and ``revenue_yoy_pct``.
 
         Args:
             ticker:           Filter to a single symbol.

{valuein_sdk-3.2.0 → valuein_sdk-3.3.1}/valuein_sdk/queries/SQL_CHEATSHEET.md

@@ -14,11 +14,11 @@ Common patterns for querying the Valuein data lake. The SDK executes these again
 | `entity` | 16K+ | Company master (use for fields not in `references` — `business_address`, `former_names`, `is_foreign`, `flags`, …). |
 | `security` | 18K+ | Ticker history — SCD Type 2 with `valid_from` / `valid_to`. Filter `is_primary_ticker = TRUE` for one row per CIK on multi-share-class issuers. |
 | `index_membership` | 50K+ | Historical index membership keyed on `cik` (since migration 0015). `effective_date` / `removal_date` half-open `[)` window. SP500 / NASDAQ100 / RUSSELL3000 / WILSHIRE5000. |
-| `taxonomy_guide` | ~150 | Definitions for every `standard_concept` value used in `fact`. |
+| `taxonomy_guide` | 292 | Definitions for every `standard_concept` value used in `fact`. |
 | `valuation` | ~500K | Pre-computed intrinsic values per (entity_id, valuation_date, model_type): `dcf` / `dcf_fcf` / `ddm`. |
 | `ratio` | ~1.2M | Pipeline-computed financial ratios (recomputed each pipeline run). Filter by `category`. |
-| `factor_scores` | ~16K | Cross-sectional factor scores + percentile ranks (10 factors + composite_rank). |
-| `earnings_signals` | ~250K | Trailing 4-quarter EPS trend + surprise %; YoY revenue growth. |
+| `factor_scores` | ~16K | Cross-sectional factor scores + percentile ranks + a proprietary composite_rank. |
+| `earnings_signals` | ~250K | Proprietary TTM EPS trend estimate + surprise %; YoY revenue growth. |
 
 ---
 

{valuein_sdk-3.2.0 → valuein_sdk-3.3.1}/valuein_sdk/queries/blockholders.sql

@@ -40,7 +40,7 @@ all_filings AS (
             ELSE 'OTHER'
         END                                              AS schedule_prefix,
         COALESCE(b.filer_cik, b.filer_name)              AS filer_key
-    FROM beneficial_ownership b
+    FROM insider_ownership b
     WHERE b.subject_entity_id = (SELECT cik FROM target_entity)
 ),
 going_active_filers AS (

{valuein_sdk-3.2.0 → valuein_sdk-3.3.1}/valuein_sdk/queries/earnings_surprise_alpha.sql

@@ -2,9 +2,9 @@
 --
 -- Parquet schema 2.3.0+ ships an `earnings_signals` table that pre-computes:
 --
---   eps_trend_est    — trailing 4-quarter average of EPSDiluted
+--   eps_trend_est    — proprietary trailing EPS trend estimate
 --   eps_actual       — most recent reported EPSDiluted
---   eps_surprise_pct — (actual - trend_est) / |trend_est|
+--   eps_surprise_pct — actual EPS vs. the trend estimate
 --   revenue_yoy_pct  — quarterly revenue YoY change
 --
 -- Use to surface companies where the most recent quarter materially beat or

{valuein_sdk-3.2.0 → valuein_sdk-3.3.1}/valuein_sdk/queries/factor_screen_top_quintile.sql

@@ -1,8 +1,8 @@
 -- Top-quintile cross-sectional factor screen using pre-computed factor_scores.
 --
--- Parquet schema 2.3.0+ ships a `factor_scores` table with 10 raw factor
+-- Parquet schema 2.3.0+ ships a `factor_scores` table with raw factor
 -- values plus a percentile-rank column for each (`*_rank`, range 0.0–1.0
--- where 1.0 is best) and an equal-weight `composite_rank`.  The ranks are
+-- where 1.0 is best) and a proprietary `composite_rank`.  The ranks are
 -- stable cross-sectional within the latest pipeline run — so this query is
 -- a single scan, no join-and-rank gymnastics.
 --