drc-vantage 1.0.7__py3-none-any.whl

drc_vantage-1.0.7.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: drc-vantage
+Version: 1.0.7
+Summary: Python SDK for the DRC Vantage data platform
+Project-URL: Homepage, https://github.com/nathan294/vantage
+Project-URL: Repository, https://github.com/nathan294/vantage
+Project-URL: Issues, https://github.com/nathan294/vantage/issues
+Author: DRC
+License-Expression: LicenseRef-Proprietary
+Keywords: analytics,data,governance,postgresql,sdk,vantage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: boto3>=1.43.46
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain-openai>=0.3.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: numpy>=2.5.1
+Requires-Dist: pillow>=11.0.0
+Requires-Dist: psycopg[binary]>=3.3.4
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: resend>=2.32.2
+Requires-Dist: scikit-learn>=1.9.0
+Requires-Dist: sqlalchemy>=2.0.51
+Description-Content-Type: text/markdown
+
+# DRC Vantage SDK
+
+Python SDK for the [Vantage](https://github.com/nathan294/vantage) data platform: dataset sync, validation, analysis, KPI computation, and smart cockpit pipelines.
+
+## Requirements
+
+- Python 3.13+
+
+## Installation
+
+```bash
+pip install drc-vantage
+```
+
+## Quick start
+
+```python
+from vantage import Client, Dataset
+
+client = Client(
+    postgres_host="localhost",
+    postgres_user="postgres",
+    postgres_password="secret",
+    postgres_database="vantage",
+)
+
+dataset = Dataset(
+    client=client,
+    location={"schema": "marts", "table": "customers"},
+    dataset_name="Customers",
+    dataset_type="TABLE",
+)
+dataset.sync()
+```
+
+## License
+
+Proprietary. All rights reserved.

drc_vantage-1.0.7.dist-info/RECORD

@@ -0,0 +1,108 @@
+vantage/__init__.py,sha256=IwtLxN9hObbtEWHAFxr41FPcKYr5DdWJhihyPOs41tk,485
+vantage/client.py,sha256=3LlIfQM-oTNwYrfZt8jPMgDWlJ6lwYRi6iRJ9CTLBRw,4627
+vantage/core/logo.py,sha256=Q6AKz32TNlhQpDpFmsKdTb6ZqJP2U9p2APGJmm2un1g,5255
+vantage/core/organization.py,sha256=WQT_zi2PJshUZhkHlD7u49oltqy-165o79eRuEC2CyM,1976
+vantage/core/s3.py,sha256=6auzMfiJ1mQwDokEjqEua7h9fMT4Aw65S-D3BRM9DNY,884
+vantage/data_sources/data_source.py,sha256=vdsXpxDOE0n49Hj_erfux_OG69A5JVSRBuEVTQk4M_I,3198
+vantage/data_sources/data_source_category.py,sha256=6pmOhrRLeJOcFJnpWZ_qqwKpvMi0sP_B5GyoIW650-Q,1286
+vantage/data_sources/sync/data_source_helpers.py,sha256=bDAER2ueQD0e0Qfi6phH-FOfftthzHBFlf_5KmRT5mg,676
+vantage/data_sources/sync/sync_data_source.py,sha256=COLBhuDPo0r2rnwlLWjJZnRZZQWGJmmKhyQv9kH9Cw0,3016
+vantage/data_sources/sync/sync_data_source_category.py,sha256=PEk46tcHGwVnPt3-aj78iQptEgG539wGjOOdXsZeUqM,2572
+vantage/data_storage_system/data_storage_system.py,sha256=4By8m9xgEJxHh2a226DGPR4PLKWRk2rX8CcF-Brc9gI,3296
+vantage/data_storage_system/sync/data_storage_system_helpers.py,sha256=rYQPT05MtAWTHzH_I0IfYCetBeF7hkJ1NtFWFJcCmK4,1661
+vantage/data_storage_system/sync/sync_data_storage_system.py,sha256=2Wbaj8MokWGhv7g-iHP_DKzrcPd3zo95PKDu0Mu5SJQ,3208
+vantage/datasets/dataset.py,sha256=D7ITADuz21xyLpUsL-O_AGeZZN-tzWvuXnbz-EKFL7s,7006
+vantage/datasets/alerts/check_alert.py,sha256=gdspbWip-Z6t3ez358mR82Ym90ANVySCEMvRTt5YsPA,838
+vantage/datasets/alerts/check_dataset_alerts.py,sha256=avDHyqvLGxNQiAQkBg7mPuaytSM8XW7k8LXfhbg40To,985
+vantage/datasets/alerts/email.py,sha256=E1YhWLVlrHoqJRjYZQUCLLweL-9Cm8rHNLD-die3irk,6905
+vantage/datasets/alerts/evaluate_alert.py,sha256=00N9cpCmJ-IZ7pT4iwuCMRSGEfdzve4m2Wbif3JQ-Hg,10003
+vantage/datasets/alerts/queries.py,sha256=1pXs30lBHvvCIaiv9zA3RS4a4vlwM0m7zbcke0DZn9o,4275
+vantage/datasets/alerts/run_alert_check.py,sha256=uvNSNDmPQ_7YUL2FoRdjpKXjYmU3_TeH7W2eq018G14,3139
+vantage/datasets/analysis/analyze_dataset.py,sha256=ftypJJDMPmGoHSlGXjAwtXzgwn4TtGjhVWiANrXXQP4,669
+vantage/datasets/analysis/column_analysis.py,sha256=eII0mbn6-XMCXdAl0nPlKxq7CFH8OzpTu6uJIdwye0Y,14471
+vantage/datasets/analysis/health_score.py,sha256=WUEYz6YA3yuI8A_VdT2g0R-ZSMgx2ZwdAVITphzT6gE,5156
+vantage/datasets/analysis/list_dataset_ids.py,sha256=UmZq4VsFzpDUI-tKeOzPLYuuUEwToan06iqx-KJEyRM,485
+vantage/datasets/analysis/run_analysis.py,sha256=IsVOISHwtebnq-utRbhWDlotnHrcQyxkhEEJ2rMK9f4,9760
+vantage/datasets/analysis/smart_alerts.py,sha256=B4jfN2pfEf6FXPZ0kQ0PKhmtEwlYIYSn78GIlBuj3IQ,4465
+vantage/datasets/analysis/metrics/anomalies.py,sha256=JQ0zhz2lYqeTppcCvw-34lnfErHpCL4FfmBUXC62xSU,5931
+vantage/datasets/analysis/metrics/completion.py,sha256=K8TgO36-GlmQxZfp2vtE8jeYQj7uvgParxgSbG5toYU,3552
+vantage/datasets/analysis/metrics/row_count.py,sha256=w4HrdE01uG4xW2cl8WT8khZ4pEM5GEerTTq7KeGOquc,4528
+vantage/datasets/linking/assign_dataset_data_sources.py,sha256=Ki4tdhea12vCpdLyaGDyPfxFG_qcHvcmg2at_-_NhrY,3226
+vantage/datasets/sync/dataset_helpers.py,sha256=mVTRHWpk50SQSvL2iO4flkr8-1CYGBD1dmw9i0zD2O0,9803
+vantage/datasets/sync/materialized_views.py,sha256=_3vVTVqyYh6HHa3Es7bq2Lnrpjvz56wxK-cU0JHTazQ,4349
+vantage/datasets/sync/sync_dataset.py,sha256=oKYAn9_BPD04n_rEOcU0Fm1k-UMF8CGqAQcP6crRS7c,8456
+vantage/datasets/teams/assign_dataset_to_team.py,sha256=5YT9aUrrO-OQo5UXCKxdWTSjDkXc1WNpzmGcQXB8jbI,9004
+vantage/datasets/teams/team_helpers.py,sha256=aijTYDAjtrpuIGEl_872j-7y_jfmsr3hp7d-9GyZWMY,1912
+vantage/datasets/validations/get_dataset_info.py,sha256=Rf6H6Jy7Oqh1Odn4G_OUxp61uujhcav83K4MBecZWwY,2079
+vantage/datasets/validations/get_dataset_validations.py,sha256=3fQzdc7Yj6bfVYZVDNJZhW6DQU9L60WteYuNyKHR3I8,3514
+vantage/datasets/validations/recommend_validations.py,sha256=YnoeP5j6fls0o562nyPOGb16NxFUaFZo31p7RaEVURM,5348
+vantage/datasets/validations/rule_config.py,sha256=eYnfcCIgCJxc8osHTwh54PFniAgJyw4Sk8WxbcM1Fgo,6093
+vantage/datasets/validations/rule_config_reference.json,sha256=l6gnTuHpxxpOP72j4epfXct5Y-OrwzoHuTuxLmm-wwE,5212
+vantage/datasets/validations/run_all_dataset_validation_suites.py,sha256=rKtnchFOI_-bZMR0CEJh7V2MPmEg8E3XYyGZfnf4Spc,1079
+vantage/datasets/validations/run_dataset_validations.py,sha256=E4KWj2jimFKx_CRI2f4Y9hCQn_18Y3aNyrNfU2-_Wkk,497
+vantage/datasets/validations/run_validation.py,sha256=1LCkfbuZRH-RLNJcqCm0xnIjf6ZsYqQVJD5NM2lQdC0,656
+vantage/datasets/validations/run_validation_rule.py,sha256=pIUz0Sbwdz842Nk5M_fHlTHo8PmBi8MNtWaE9DmIr2Y,4337
+vantage/datasets/validations/run_validation_suite.py,sha256=xiaKOUSBMENl_dFrTMgcDVaSlwQcChpF1dgXK8CgWpk,6474
+vantage/datasets/validations/schemas.py,sha256=9CpqZvzHV9eA3DOJz1lK_259cMkotVDNy5SBXrQfvi4,5877
+vantage/datasets/validations/checks/__init__.py,sha256=cldmnJuBUq3ws4-eC0iVJCtyuqduy5SlLkTlkCyXEsA,96
+vantage/datasets/validations/checks/check_column_avg.py,sha256=BmQNXXcvdKO9cENc14yMZY4EXZ_dGtPLKWwBHTIUWBI,2252
+vantage/datasets/validations/checks/check_column_between.py,sha256=WyE9yPMqAGF-swOJRX02vY-kAJe4fa7V9KAVSJG7enA,1897
+vantage/datasets/validations/checks/check_column_count_distinct.py,sha256=oef1gwdj4EDww1A8e7msn-eubYs233ky7tjRy9pxAC8,2104
+vantage/datasets/validations/checks/check_column_count_not_null.py,sha256=UpHYrs0AMK5WTTsbA7tdJFfLpk9-4hmq0iFDKhOkMTA,2086
+vantage/datasets/validations/checks/check_column_count_null.py,sha256=J-NTXvb4QBt_67qv26zScaZ3hHR0RiW4gDyn7VonEFA,1830
+vantage/datasets/validations/checks/check_column_max.py,sha256=3mExqkbXjQmxsEJK17M9LZK98xR81qzLJx-5c4_nUyI,1951
+vantage/datasets/validations/checks/check_column_max_length.py,sha256=_31vYeiTzf92iv3W7ICKoLui0ec6W6JmaftkPd4gPeA,1775
+vantage/datasets/validations/checks/check_column_mean.py,sha256=LKy13YqwNwu3EPNqO1dVFkFW8mJPGu2410BUuLrK6LM,2265
+vantage/datasets/validations/checks/check_column_median.py,sha256=os1xWke3dHop0izqMwH3raUq8yP7KLlZsPSUrYEIEdc,2377
+vantage/datasets/validations/checks/check_column_min.py,sha256=IJ_Y1HNu71b3QrOQFeUIK3eJbd2FL_VpWK_88rjCz0A,1948
+vantage/datasets/validations/checks/check_column_min_length.py,sha256=GV1Ujk8fpkz1RIJZGGcsyImaUEUnel74uik7EiAFxQM,1776
+vantage/datasets/validations/checks/check_column_not_between.py,sha256=pkgHMoT33FiNt8ElK31LdfU10dxlInzeqvtIhY7w8NA,1907
+vantage/datasets/validations/checks/check_column_not_null.py,sha256=abQz3N-ySgl7nBK6Yw_iPQsjyfDYdI-WaRB3Dc9FS6k,1346
+vantage/datasets/validations/checks/check_column_percent_not_null.py,sha256=5Q97lrnSGCCfurLMNRhRfSzWSEw9TtJVmmvNQ6W0XmI,2534
+vantage/datasets/validations/checks/check_column_percent_null.py,sha256=wuirX2XytzHIso212-bbwjJqcyLe6NkLA0XAh__8ies,2460
+vantage/datasets/validations/checks/check_column_percentile.py,sha256=YHXvtabK_kLzaJOBnNYoT40TsvCIZ6lN1OaRzyZSivY,2670
+vantage/datasets/validations/checks/check_column_regex_match.py,sha256=ZB4WS9eSxMXsYnZmq7d8LznAqIFSht5lfXmeAbvLEXI,1732
+vantage/datasets/validations/checks/check_column_regex_not_match.py,sha256=RA8idqhQvnNfB1IlauiT5EowJ4bemuG0p0ejb48Qp6A,1749
+vantage/datasets/validations/checks/check_column_stddev.py,sha256=QaUi17JMhb1NbK8AEpztrkFqvUEhL10_xMxq8lBCjwg,2321
+vantage/datasets/validations/checks/check_column_sum.py,sha256=EUW7INL63Tp4e_5KclYEVOEdvAbjKRvfSKvzt1oPWm0,2060
+vantage/datasets/validations/checks/check_column_unique.py,sha256=SDZV8w3x9RIPTUVff239ivn8luWBcBh2RutOkJOOFIM,1434
+vantage/datasets/validations/checks/check_column_values_in_set.py,sha256=rrj_3ksfPFlVM8yVueAO5oM-998pz5gI1Qt6qWrn9zU,1953
+vantage/datasets/validations/checks/check_column_values_not_in_set.py,sha256=KFAh51KfbOTNm-WajjgyL53M2xzU6HYR66hup_Cf02A,1919
+vantage/datasets/validations/checks/check_custom_sql.py,sha256=Tq0IWZaRNR-yKRbZzjxB6gKpoDiIdHVVuHTzI7-w1VM,1622
+vantage/datasets/validations/checks/check_table_duplicate_rows.py,sha256=nq_9xWmioqCXm9SQDsw11-2711I8IsTjA8RbPdF1uAk,1678
+vantage/datasets/validations/checks/check_table_freshness.py,sha256=OdWKkI0M1Sx2iRJXJ92I_l8uzm3h6BO6S0RHSfAnp5o,2708
+vantage/datasets/validations/checks/check_table_row_count.py,sha256=UrxIlQ7dSVNZRs66sXzYmP_Jw9AEN2AIRvq0skHfTFs,1610
+vantage/datasets/validations/checks/check_table_row_count_between.py,sha256=jnw_VSTpErPvcrqVlhirFRgNp-DLOrtz7TiYKdxlvCw,1392
+vantage/datasets/validations/checks/check_table_schema_change.py,sha256=3vGbhc1buvqNRdYO6RXjdh-8JSphfULxpMafFL8dIFI,712
+vantage/datasets/validations/checks/run_check.py,sha256=NRoI-c0h35eDkuIPIsDLpARsDZgsO4QiNqnqlzT1nsA,6273
+vantage/datasets/validations/checks/sql_helpers.py,sha256=IDAiuVyBxfw3hfV3k5OuYcBNUmVAtI8ipRDljAUdWow,2522
+vantage/datasets/validations/recommendations/dedupe.py,sha256=Hu84bJ55VcwJwPhxkANgrqKbRpjxtMY1wut4MugcQa4,4921
+vantage/datasets/validations/recommendations/fetch.py,sha256=YYMZfAMHGp8jqmnIqa2L4_Wrh96gdrcUrKVZL6ryvPY,11834
+vantage/datasets/validations/recommendations/llm.py,sha256=ofDx55M01DdgN5xO4860zwUkhtgx1YQ5To1hiwyemzQ,2872
+vantage/datasets/validations/recommendations/normalize.py,sha256=VnmsSCsXHrxmx1eW-HRgkvrBoFvY6KlmioscuazPKDQ,2437
+vantage/datasets/validations/recommendations/prompt.py,sha256=yG3f10VZ1XZv9uzOznHd3h1a9j8XTZIYiFPh-EpU0nI,5914
+vantage/datasets/validations/recommendations/save.py,sha256=5-MLHvY-TKA1PvQ5oj_0y-UYybT_6tiykXlohh8q_nw,6030
+vantage/datasets/validations/recommendations/schemas.py,sha256=DV4at5srdG8nTEY5My9mnd7ljdSgYS5HMI_mZ988vwc,2504
+vantage/kpis/compute/compute.py,sha256=18h_lnPDZCerdez5wdD7Ng2Z4f1-4Qll_h0_M8qfBfc,6818
+vantage/kpis/compute/compute_manual.py,sha256=8HOAfb_77AfnoeY55C8AyLtDkv05mGJfRItaYU1TGoY,15517
+vantage/kpis/compute/compute_sql.py,sha256=nXajHqIgb3cOUMG7v3pMxd7nrs7U3H2R5Gd1C7PcDqM,1213
+vantage/kpis/compute/fetch.py,sha256=Yy2oOeaVa8p_wCo2JUBo1aXo1kTspcg8xIhwC74Csdw,1176
+vantage/kpis/compute/save.py,sha256=QVZNMDTteWizSmItcr0QxqGhK-y76QmSGe6Exq46gT0,2291
+vantage/kpis/compute/schemas.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vantage/smart_cockpit/configuration.py,sha256=Sc0xzGRhyiM2wwn78aLiIzT4tELkxprwojFhJvjs8iY,1003
+vantage/smart_cockpit/ai_summary/fetch.py,sha256=ro-z5xCd5PrN33q49enstP0Bvqz0PgqhvW7ThsYuJ9A,3938
+vantage/smart_cockpit/ai_summary/llm.py,sha256=RzTyd5xnOmgNDTbdsKgqGBLyu8H_S55WCNl65wsTjA4,4012
+vantage/smart_cockpit/ai_summary/prompt.py,sha256=7WdoVZs7fXOAiCvc2VUxGmpg1Ml9ooZSfLqQTUb4H20,3749
+vantage/smart_cockpit/ai_summary/save.py,sha256=Ofryr-GrVeiIqcRzIgeixjzF4sgg6LxikrpArhkOW2I,2653
+vantage/smart_cockpit/ai_summary/schemas.py,sha256=h2KoqFFoxuUnr1fmGaTjbucoXjqIGM2DHPzBnDwqWkM,471
+vantage/smart_cockpit/company_news/llm.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vantage/smart_cockpit/company_news/save.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vantage/smart_cockpit/company_news/schemas.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vantage/smart_cockpit/kpi_insights/fetch.py,sha256=IUGr0HDinkuhOGhK5UGWv7Ge1SUxyfrBRYQd-zaZ1NU,2219
+vantage/smart_cockpit/kpi_insights/llm.py,sha256=4IbZQK2N5QcvW5kBNZY0t0lRgdznQyK4nC1DzbfdMN8,1777
+vantage/smart_cockpit/kpi_insights/prompt.py,sha256=0T_n9NXC3UVkoWe-8EtETenLGje7FlsLKPzDRqGOyV4,6078
+vantage/smart_cockpit/kpi_insights/save.py,sha256=NLxhxcM2cCKizk2auXgEq9_0TDc2nkoWtdphEitVvxk,2624
+vantage/smart_cockpit/regenerate/generate_missing_kpi_insights.py,sha256=hbSPg3mm6RuChfKQQTvkFSO9nwCTy_OqEJSjfBu4Z3Q,1001
+drc_vantage-1.0.7.dist-info/METADATA,sha256=Ay1L1uQ47NsZNXkLbFygh1AubWn_j6Ca6rMAxnv1TZw,1920
+drc_vantage-1.0.7.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+drc_vantage-1.0.7.dist-info/RECORD,,

drc_vantage-1.0.7.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vantage/__init__.py

@@ -0,0 +1,16 @@
+"""DRC Vantage SDK — platform data pipelines."""
+
+from vantage.client import Base, Client
+from vantage.data_sources.data_source import DataSource
+from vantage.data_sources.data_source_category import DataSourceCategory
+from vantage.data_storage_system.data_storage_system import DataStorageSystem
+from vantage.datasets.dataset import Dataset
+
+__all__ = [
+    "Base",
+    "Client",
+    "DataSource",
+    "DataSourceCategory",
+    "DataStorageSystem",
+    "Dataset",
+]

vantage/client.py

@@ -0,0 +1,126 @@
+"""Vantage SDK client: database access and runtime configuration."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Generator
+from urllib.parse import quote_plus
+
+from loguru import logger
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def _get_secret(value: Any) -> str:
+    if hasattr(value, "get_secret_value"):
+        return value.get_secret_value()
+    return str(value)
+
+
+class Client:
+    """Entry point for SDK runtime configuration and database access."""
+
+    def __init__(
+        self,
+        *,
+        vantage_schema: str = "vantage",
+        generate_ai_validations: bool = False,
+        postgres_host: str | None = None,
+        postgres_port: int = 5432,
+        postgres_user: str | None = None,
+        postgres_password: Any | None = None,
+        postgres_database: str = "vantage",
+        openai_api_key: str | None = None,
+        resend_api_key: str | None = None,
+        s3_client: Any | None = None,
+        s3_bucket_name: str | None = None,
+    ) -> None:
+        self.vantage_schema = vantage_schema
+        self.generate_ai_validations = generate_ai_validations
+        self.postgres_host = postgres_host
+        self.postgres_port = postgres_port
+        self.postgres_user = postgres_user
+        self.postgres_password = postgres_password
+        self.postgres_database = postgres_database
+        self.openai_api_key = openai_api_key
+        self.resend_api_key = resend_api_key
+        self.s3_client = s3_client
+        self.s3_bucket_name = s3_bucket_name
+        self._engine: Engine | None = None
+        self._session_maker: sessionmaker[Session] | None = None
+
+    @property
+    def is_postgres_configured(self) -> bool:
+        return bool(self.postgres_host and self.postgres_user and self.postgres_password)
+
+    @property
+    def is_s3_configured(self) -> bool:
+        return self.s3_client is not None and self.s3_bucket_name is not None
+
+    def _build_postgres_url(self, database: str | None = None) -> str:
+        if not self.is_postgres_configured:
+            raise ValueError("PostgreSQL is not configured. Set POSTGRES_* variables in your .env file.")
+
+        db = database or self.postgres_database
+        password = quote_plus(_get_secret(self.postgres_password))
+        user = quote_plus(self.postgres_user)  # type: ignore[arg-type]
+        return f"postgresql+psycopg://{user}:{password}@{self.postgres_host}:{self.postgres_port}/{db}"
+
+    def get_engine(self) -> Engine:
+        if self._engine is None:
+            self._engine = create_engine(self._build_postgres_url(), pool_pre_ping=True)
+        return self._engine
+
+    def get_session_maker(self) -> sessionmaker[Session]:
+        if self._session_maker is None:
+            self._session_maker = sessionmaker(
+                bind=self.get_engine(),
+                class_=Session,
+                expire_on_commit=False,
+            )
+        return self._session_maker
+
+    @contextmanager
+    def get_session(self) -> Generator[Session, None, None]:
+        session = self.get_session_maker()()
+        try:
+            yield session
+            session.commit()
+        except Exception:
+            session.rollback()
+            raise
+        finally:
+            session.close()
+
+    def ensure_database_exists(self) -> None:
+        if not self.is_postgres_configured:
+            logger.warning("Database configuration is not valid, skipping database creation check")
+            return
+
+        engine = create_engine(
+            self._build_postgres_url("postgres"),
+            pool_pre_ping=True,
+            isolation_level="AUTOCOMMIT",
+        )
+
+        try:
+            with engine.connect() as conn:
+                exists = conn.execute(
+                    text("SELECT 1 FROM pg_database WHERE datname = :dbname"),
+                    {"dbname": self.postgres_database},
+                ).scalar()
+
+                if exists:
+                    logger.info(f"Database '{self.postgres_database}' already exists")
+                    return
+
+                logger.info(f"Database '{self.postgres_database}' does not exist, creating it...")
+                conn.execute(text(f'CREATE DATABASE "{self.postgres_database}"'))
+                logger.info(f"Database '{self.postgres_database}' created successfully")
+        finally:
+            engine.dispose()

vantage/core/logo.py

@@ -0,0 +1,157 @@
+"""Prepare and upload data source logos to S3 (mirrors frontend logo pipeline)."""
+
+import io
+import mimetypes
+from pathlib import Path
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+from uuid import uuid4
+
+from loguru import logger
+from PIL import Image
+from vantage.client import Client
+from vantage.core.s3 import upload_object
+
+SVG_MIME = "image/svg+xml"
+MAX_INPUT_BYTES = 8 * 1024 * 1024
+LOGO_MAX_DIMENSION = 200
+WEBP_QUALITY = 85
+LOGO_FETCH_USER_AGENT = "demo-flows/0.1 (Foresyn; data source logo sync)"
+
+
+def get_extension_for_logo_content_type(content_type: str) -> str | None:
+    normalized = content_type.split(";")[0].strip().lower()
+    mapping = {
+        "image/webp": "webp",
+        "image/svg+xml": "svg",
+        "image/png": "png",
+        "image/jpeg": "jpg",
+        "image/jpg": "jpg",
+    }
+    return mapping.get(normalized)
+
+
+def prepare_data_source_logo(
+    image_bytes: bytes,
+    *,
+    filename: str | None = None,
+    content_type: str | None = None,
+) -> tuple[bytes, str]:
+    """
+    Prepare a logo for upload.
+
+    Raster images: resize/compress to WebP, max 200×200px.
+    SVG: kept as vector text (no raster compression), basic structure check.
+    """
+    if len(image_bytes) > MAX_INPUT_BYTES:
+        raise ValueError("FILE_TOO_LARGE")
+
+    guessed_type = content_type or (
+        mimetypes.guess_type(filename or "")[0] if filename else None
+    )
+    looks_svg = guessed_type == SVG_MIME or (
+        filename and filename.lower().endswith(".svg")
+    )
+
+    if looks_svg:
+        return _prepare_svg_logo(image_bytes)
+
+    try:
+        return _prepare_raster_logo(image_bytes)
+    except ValueError:
+        raise
+    except Exception as exc:
+        raise ValueError("COMPRESS_FAILED") from exc
+
+
+def upload_data_source_logo(client: Client, image_buffer: bytes, content_type: str) -> str:
+    """
+    Upload a data source logo to S3. Uses a random object name (never the client filename).
+
+    Returns:
+        S3 object key to store in ``DataSource.logoUrl`` (e.g. ``logos/uuid.webp``)
+    """
+    ext = get_extension_for_logo_content_type(content_type)
+    if not ext:
+        raise ValueError(f"Unsupported logo content type: {content_type}")
+
+    normalized_type = content_type.split(";")[0].strip().lower()
+    object_key = f"logos/{uuid4()}.{ext}"
+
+    try:
+        upload_object(
+            client=client,
+            object_key=object_key,
+            body=image_buffer,
+            content_type=normalized_type or f"image/{'jpeg' if ext == 'jpg' else ext}",
+        )
+        logger.info("Uploaded data source logo to %s", object_key)
+        return object_key
+    except Exception as exc:
+        logger.exception("Error uploading data source logo to S3")
+        raise RuntimeError(
+            f"Failed to upload data source logo: {exc if isinstance(exc, Exception) else 'Unknown error'}"
+        ) from exc
+
+
+def upload_data_source_logo_from_path(client: Client, path: str | Path) -> str:
+    """Read a local file, prepare it, upload to S3, and return the object key."""
+    file_path = Path(path)
+    if not file_path.is_file():
+        raise FileNotFoundError(f"Logo file not found: {file_path}")
+
+    raw = file_path.read_bytes()
+    prepared, content_type = prepare_data_source_logo(raw, filename=file_path.name)
+    return upload_data_source_logo(client, prepared, content_type)
+
+
+def upload_data_source_logo_from_url(client: Client, url: str) -> str:
+    """Download a remote image, prepare it, upload to S3, and return the object key."""
+    if not client.is_s3_configured:
+        return url
+
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(f"Invalid logo URL: {url}")
+
+    request = Request(url, headers={"User-Agent": LOGO_FETCH_USER_AGENT})
+    with urlopen(request, timeout=30) as response:
+        raw = response.read()
+        content_type = response.headers.get("Content-Type")
+        filename = Path(parsed.path).name or None
+
+    prepared, content_type = prepare_data_source_logo(
+        raw, filename=filename, content_type=content_type
+    )
+    return upload_data_source_logo(client, prepared, content_type)
+
+
+def _prepare_svg_logo(image_bytes: bytes) -> tuple[bytes, str]:
+    try:
+        text = image_bytes.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ValueError("INVALID_SVG") from exc
+
+    if not text.strip().lstrip().lower().startswith("<svg"):
+        raise ValueError("INVALID_SVG")
+
+    return text.encode("utf-8"), SVG_MIME
+
+
+def _prepare_raster_logo(image_bytes: bytes) -> tuple[bytes, str]:
+    with Image.open(io.BytesIO(image_bytes)) as img:
+        img.thumbnail(
+            (LOGO_MAX_DIMENSION, LOGO_MAX_DIMENSION), Image.Resampling.LANCZOS
+        )
+
+        if img.mode in ("RGBA", "LA") or (
+            img.mode == "P" and "transparency" in img.info
+        ):
+            img = img.convert("RGBA")
+        else:
+            img = img.convert("RGB")
+
+        out = io.BytesIO()
+        img.save(out, format="WEBP", quality=WEBP_QUALITY, method=6)
+
+    return out.getvalue(), "image/webp"

vantage/core/organization.py

@@ -0,0 +1,51 @@
+"""Shared helpers for resolving platform organizations."""
+
+from typing import Optional
+
+from sqlalchemy import text
+
+from vantage.client import Client
+
+
+def get_organization_by_slug(client: Client, organization_slug: str) -> Optional[str]:
+    with client.get_session() as session:
+        organization = session.execute(
+            text(f"SELECT id FROM {client.vantage_schema}.organization WHERE slug = :organization_slug"),
+            {"organization_slug": organization_slug},
+        ).fetchone()
+        return organization[0] if organization else None
+
+
+def get_organization_count(client: Client) -> int:
+    with client.get_session() as session:
+        row = session.execute(text(f"SELECT COUNT(*) FROM {client.vantage_schema}.organization")).fetchone()
+        return int(row[0]) if row else 0
+
+
+def get_single_organization_id_if_only_one_exists(client: Client) -> Optional[str]:
+    with client.get_session() as session:
+        rows = session.execute(text(f"SELECT id FROM {client.vantage_schema}.organization LIMIT 2")).fetchall()
+        if len(rows) == 1:
+            return rows[0][0]
+        return None
+
+
+def resolve_organization_id(client: Client,
+    organization_id: Optional[str] = None,
+    organization_slug: Optional[str] = None,
+) -> str:
+    if organization_slug:
+        org_id = get_organization_by_slug(client, organization_slug=organization_slug)
+        if not org_id:
+            raise ValueError(f"Organization with slug '{organization_slug}' not found")
+        return org_id
+    if organization_id:
+        return organization_id
+    org_id = get_single_organization_id_if_only_one_exists(client)
+    if org_id:
+        return org_id
+    if get_organization_count(client) == 0:
+        raise ValueError("No organization found; provide organization_id or organization_slug")
+    raise ValueError(
+        "Multiple organizations found; provide organization_id or organization_slug"
+    )

vantage/core/s3.py

@@ -0,0 +1,31 @@
+"""S3-compatible object storage client (MinIO, AWS S3, etc.)."""
+
+from typing import Any
+
+from vantage.client import Client
+
+
+def get_s3_client(client: Client) -> Any:
+    if not client.is_s3_configured:
+        raise ValueError("S3 is not configured. Pass s3_client and s3_bucket_name to Client.")
+    return client.s3_client
+
+
+def upload_object(
+    client: Client,
+    object_key: str,
+    body: bytes,
+    content_type: str,
+) -> str:
+    """Upload bytes to the configured bucket. Returns the object key."""
+    if not client.is_s3_configured:
+        raise ValueError("S3 is not configured. Pass s3_client and s3_bucket_name to Client.")
+
+    client.s3_client.put_object(
+        Bucket=client.s3_bucket_name,
+        Key=object_key,
+        Body=body,
+        ContentLength=len(body),
+        ContentType=content_type,
+    )
+    return object_key

vantage/data_sources/data_source.py

@@ -0,0 +1,71 @@
+"""Platform data source definition."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Union
+
+from vantage.client import Client
+from vantage.data_sources.data_source_category import DataSourceCategory
+from vantage.data_sources.sync.data_source_helpers import get_data_source_id_by_slug
+from vantage.core.logo import (
+    upload_data_source_logo_from_path,
+    upload_data_source_logo_from_url,
+)
+from vantage.data_sources.sync.sync_data_source import sync_data_source
+from vantage.core.organization import resolve_organization_id
+
+
+@dataclass
+class DataSource:
+    """Platform data source."""
+
+    client: Client
+    slug: str  # URL-safe unique identifier for the data source
+    name: str  # Display name shown in the platform
+    category: DataSourceCategory  # Category this data source belongs to (synced first)
+    description: Optional[str] = None  # Optional summary shown in the platform UI
+    logo_path: Optional[Union[str, Path]] = None  # Local logo file uploaded on first sync
+    logo_url: Optional[str] = None  # Remote logo URL or existing platform logo URL
+    organization_id: Optional[str] = None  # Platform organization UUID (falls back to category value)
+    organization_slug: Optional[str] = None  # Organization slug (falls back to category value)
+    data_source_id: Optional[str] = field(default=None, init=False)  # Set after sync(); platform data source UUID
+
+    def _resolve_organization_id(self) -> str:
+        return resolve_organization_id(
+            self.client,
+            organization_id=self.organization_id or self.category.organization_id,
+            organization_slug=self.organization_slug or self.category.organization_slug,
+        )
+
+    def _resolve_logo_url(self) -> str:
+        if self.logo_path and self.logo_url:
+            raise ValueError("Provide only one of logo_path or logo_url")
+        if self.logo_path:
+            return upload_data_source_logo_from_path(self.client, self.logo_path)
+        if self.logo_url:
+            if self.logo_url.startswith(("http://", "https://")):
+                return upload_data_source_logo_from_url(self.client, self.logo_url)
+            return self.logo_url
+        raise ValueError("Either logo_path or logo_url is required")
+
+    def sync(self) -> str:
+        """Sync this data source (and its category) to the vantage. Returns the data source ID."""
+        org_id = self._resolve_organization_id()
+        self.category.organization_id = self.category.organization_id or org_id
+        category_id = self.category.sync()
+
+        with self.client.get_session() as session:
+            existing = get_data_source_id_by_slug(self.client, session, org_id, self.slug) is not None
+
+        logo_url = "" if existing else self._resolve_logo_url()
+
+        self.data_source_id = sync_data_source(
+            client=self.client,
+            slug=self.slug,
+            name=self.name,
+            logo_url=logo_url,
+            category_id=category_id,
+            description=self.description,
+            organization_id=org_id,
+        )
+        return self.data_source_id