Metadata-Version: 2.4
Name: valuein-sdk
Version: 0.1.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
Project-URL: Repository, https://github.com/valuein/quants
Project-URL: Bug Tracker, https://github.com/valuein/quants/issues
Author-email: Valuein Data Engineering <support@valuein.biz>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: EDGAR,SEC,duckdb,finance,fundamentals,parquet
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: duckdb>=1.1.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.32.0
Provides-Extra: research
Requires-Dist: ipykernel>=6.29.0; extra == 'research'
Requires-Dist: jupytext>=1.16.0; extra == 'research'
Requires-Dist: matplotlib>=3.8.0; extra == 'research'
Requires-Dist: numpy>=1.26.0; extra == 'research'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest>=9.0.0; extra == 'test'
Description-Content-Type: text/markdown

# 🏛️ Valuein Financial Data Essentials (FDE) - Public Resources

[![Data Quality](https://img.shields.io/badge/Data_Quality-99.9%25-green)]()
[![Update Frequency](https://img.shields.io/badge/Updates-Daily-blue)]()
[![Python](https://img.shields.io/badge/Python-3.12%2B-green)]()

**Professional-grade SEC financial data for financial analysts, quantitative researchers, data engineers, and investment teams.**

## 👋 Welcome

This repository is the official integration hub for the Valuein Financial Data Essentials feed. It hosts our Python SDK, issue tracker, schema definitions, and production usage patterns.

Our dataset includes all US public companies since 1990 (active and inactive). Both our sample and full datasets are Point-in-Time (PIT) and Survivorship-bias FREE.

## 📦 Installation
The SDK is built on top of DuckDB for lightning-fast analytical queries directly against our R2-backed data lake.

* 1. Install the SDK
Install directly from GitHub using pip:

```bash
pip install git+https://github.com/valuein/quants.git
```

### 2. Configure Credentials (.env)

The SDK automatically looks for a .env file or environment variables. Create a .env file in your project root:

```bash
# .env
ACCOUNT_ID=account_id
ACCESS_KEY_ID=your_sample_access_key
SECRET_ACCESS_KEY=your_sample_secret_key
BUCKET_NAME=sec-sample-data
```

> ### 🔑 Request Sample Data Access
> **To get free credentials for the S&P500 (historical) dataset, [Click Here](https://valuein.biz/sample-sec-data-request-access) 🚀**

FYI. Our full dataset include all US public companies since 1990 including active and inactive ones (bankrupts and mergers). Both datasets are PIT and Survivor-bias FREE.

---

## 🚀 Quickstart
The SDK handles the complex DuckDB/S3 connection logic, allowing you to focus on the data.

### Option A: Standard SQL
Run raw SQL against our standardized views (entity, security, filing, fact, etc.).

```python
from valuein_sec_sdk import ValueinClient

client = ValueinClient()

# Query NVIDIA's latest Revenue
df = client.query("""
    SELECT s.symbol, f.report_date, fa.numeric_value
    FROM security s
    JOIN filing f ON s.entity_id = f.entity_id
    JOIN fact fa  ON f.accession_id = fa.accession_id
    WHERE s.symbol = 'NVDA' AND fa.standard_concept = 'Revenues'
    ORDER BY f.report_date DESC LIMIT 5
""")
print(df)
```

### Option B: Use Built-in Templates

```python
# Run a pre-built fundamental analysis template
from valuein_sec_sdk import ValueinClient

client = ValueinClient()
df = client.run_showcase_query(
query_name="01_fundamentals_by_ticker",
ticker="AAPL",
metrics=["NetIncomeLoss", "Revenues"],
start_date="2022-01-01"
)
```

## 📚 Resources & Examples

Explore the /examples directory to see the SDK in action:

| Use Case          | File                                                            | Description                                                       |
|:------------------|:----------------------------------------------------------------|:---------------------------------------------------------|
| **New Users**     | [`examples/getting_started.py`](examples/getting_started.py)    | The 5 core join patterns (Ticker-to-Fact, Taxonomy, etc.)|
| **SDK Usage**     | [`examples/usage.py`](examples/usage.py)                        | How to use templates and pivot data for modeling. |

## 📚 Documentation
* [**Data Catalog**](docs/DATA_CATALOG.xlsx): This Valuein Data Catalog serves as a massive 105M-facts dataset and the daily workflows of institutional analysts by providing transparent governance, clear taxonomy definitions, and high-performance API integration instructions.
* [**Compliance and DDQ**](docs/COMPLIANCE_AND_DDQ.md): Due Diligence Questionnaire, data sourcing disclosures, and SOC2/Governance standards.
* [**Schema Guide**](docs/SCHEMAS.md): Entity-Relationship Diagrams (ERD) and primary key mapping across the warehouse.
* [**Methodology Guide**](docs/METHODOLOGY.md): Our logic for handling restatements, fiscal period alignment, and Point-in-Time (PIT) integrity.

## 🛡️ Data Governance & Methodology
We adhere to strict standards to ensure institutional-grade reliability.

* **SLA Policy**: Our commitment to 99.9% uptime and <2min SEC filing latency.
* * **Methodology**: We preserve "as-reported" history to support true point-in-time backtesting.
* **Restatement Handling**: We preserve "as-reported" history to support true point-in-time backtesting.


## 🆘 Support & Community
* **Found a data error?** [Open a Data Ticket](https://github.com/valuein/quants/issues/new?template=01_data_quality_report.md)
* **General Question?** [Start a Discussion](https://github.com/valuein/quants/discussions)


---

⚠️ Disclaimer: This software is for educational and research purposes only. Valuein is not responsible for financial losses incurred through the use of this SDK.

---

## License

This project is licensed under the Apache-2.0 License. See the `LICENSE` file for more information.
