bsl-model-builder

BSL Model Builder 是一個專業的軟體代理技能，旨在協助數據工程師與分析師使用 Boring Semantic Layer (BSL) 在原始數據上建構語義模型。它利用 Ibis 框架提供與數據庫無關的接口，支援包括 DuckDB、Snowflake、BigQuery 和 PostgreSQL 等多種引擎。透過將原始 SQL 邏輯抽象化為可重用的語義組件，該建構器實現了一致的指標報告、結構化的關聯邏輯以及適用於生產環境的模組化數據定義。

• 定義複雜的語義表，將 Ibis 表達式映射為具名的維度與度量。

• 透過時間截斷（如年、季、月、週、日）實現分層分組，以進行時間序列分析。

• 使用 t.all() 建構複雜的聚合邏輯，包括簡單的總和、平均值以及市場份額等比例度量。

• 透過一對多、一對一與交叉關聯處理關聯數據，支援自定義連接鍵與標準 SQL 連接類型（左、內、外連接）。

• 支援透過 Python 進行程序化定義與透過 YAML 文件進行聲明式配置，有助於版本控制與可重現的工作流。

• 利用內建的 AI 友善文檔功能，為維度和度量添加描述屬性，提升下游基於 LLM 的數據代理對模型的理解與發現能力。

• 輸入形式為原始 Ibis 關係或已建立的數據庫連接配置，輸出結構化的 SemanticTable 對象或合法的模型配置 YAML 文件。

• 使用 fluent API 鏈式調用 .with_dimensions()、.with_measures() 和 .join_many()，以保持代碼簡潔易讀。

• 確保所有定義遵循 BSL 的核心原則：盡量避免使用原始 SQL，優先使用 Ibis 原生抽象以維持跨後端的移植性。

• 為了性能考量，建議將大型項目組織成獨立的 YAML 文件，以改善團隊環境中的維護性與協作效率。

• 注意限制：必須保持與底層 Ibis 表達式的兼容性，確保所有 lambda 函數或延遲表達式（使用 _. 語法）在目標 Ibis 表的範圍內是有效的。