squirrels 0.1.0__py3-none-any.whl → 0.6.0.post0__py3-none-any.whl

squirrels/_package_data/base_project/parameters.yml

@@ -0,0 +1,142 @@
+parameters:
+  - type: SingleSelectParameter
+    factory: CreateWithOptions                            ## one of 'CreateSimple', 'CreateWithOptions', or 'CreateFromSource'
+    arguments:                                            ## arguments to specify depend on values for 'type' and 'factory'
+      name: group_by
+      label: Group By
+      description: Dimension(s) to aggregate by           ## optional, default is empty string
+      user_attribute: access_level                        ## optional, default is null
+      all_options:
+        - id: trans
+          label: Transaction
+          columns: ["id", "date", "category", "subcategory", "description"]   ## custom field
+          aliases: ["_id", "date", "category", "subcategory", "description"]  ## custom field (any alias starting with "_" will not be selected - see context.py for implementation)
+          is_default: false                               ## optional, shown is default - exists for SingleSelect or MultiSelect options only
+          user_groups: ["admin"]                          ## optional, default is empty list
+          parent_option_ids: []                           ## optional, shown is default - exists for all parameter options
+        - id: day
+          label: Day
+          columns: [date]
+          aliases: [day]
+          user_groups: ["admin", "member"]
+        - id: month
+          label: Month
+          columns: [month]
+          user_groups: ["admin", "member", "guest"]
+        - id: cat
+          label: Category
+          columns: [category]
+          user_groups: ["admin", "member", "guest"]
+        - id: subcat
+          label: Subcategory
+          columns: [category, subcategory]
+          user_groups: ["admin", "member", "guest"]
+      parent_name: null                                   ## optional, shown is default - exists for all parameter types
+  
+  - type: DateParameter
+    factory: CreateFromSource
+    arguments:
+      name: start_date
+      label: Start Date
+      description: Start date to filter transactions by
+      data_source:
+        table_or_query: SELECT min(date) AS min_date, max(date) AS max_date FROM expenses
+        default_date_col: min_date
+        min_date_col: min_date
+        max_date_col: max_date
+  
+  - type: DateParameter
+    factory: CreateWithOptions
+    arguments:
+      name: end_date
+      label: End Date
+      description: End date to filter transactions by
+      all_options:
+        - default_date: 2024-12-31
+          min_date: 2024-01-01
+          max_date: 2024-12-31
+  
+  - type: DateRangeParameter
+    factory: CreateWithOptions
+    arguments:
+      name: date_range
+      label: Date Range
+      description: Date range to filter transactions by
+      all_options:
+        - default_start_date: 2024-01-01
+          default_end_date: 2024-12-31
+          min_date: 2024-01-01
+          max_date: 2024-12-31
+  
+  - type: MultiSelectParameter
+    factory: CreateFromSource
+    arguments:
+      name: category
+      label: Category Filter
+      description: The expense categories to filter transactions by
+      data_source:
+        table_or_query: seed_categories
+        id_col: category_id
+        options_col: category
+        source: seeds                                     ## optional, default is "connection" - must be one of "connection", "seeds", or "vdl" - exists for data_source of any parameters
+        order_by_col: null                                ## optional, shown is default - exists for data_source of SingleSelect and MultiSelect
+        is_default_col: null                              ## optional, shown is default - exists for data_source of SingleSelect and MultiSelect
+        custom_cols: {}                                   ## optional, shown is default - exists for data_source of SingleSelect and MultiSelect
+        include_all: true                                 ## optional, shown is default - exists for data_source of MultiSelect only
+        order_matters: false                              ## optional, shown is default - exists for data_source of MultiSelect only
+        user_group_col: null                              ## optional, shown is default - exists for data_source of any parameters
+        connection_name: default                          ## optional, shown is default - exists for data_source of any parameters
+  
+  - type: MultiSelectParameter
+    factory: CreateFromSource
+    arguments:
+      name: subcategory
+      label: Subcategory Filter
+      description: The expense subcategories to filter transactions by (available options are based on selected value(s) of 'Category Filter')
+      parent_name: category
+      data_source:
+        table_or_query: seed_subcategories
+        id_col: subcategory_id
+        options_col: subcategory
+        source: seeds
+        parent_id_col: category_id                        ## optional, default is null - exists for all parameter types
+  
+  - type: NumberParameter
+    factory: CreateWithOptions
+    arguments:
+      name: min_filter
+      label: Amounts Greater Than
+      description: Number to filter on transactions with an amount greater than this value
+      all_options:
+        - min_value: 0
+          max_value: 300
+          increment: 10                                   ## optional, default is 1 - exists for Number and NumberRange options
+          default_value: null                             ## optional, shown is default - exists for Number options only
+  
+  - type: NumberParameter
+    factory: CreateFromSource
+    arguments:
+      name: max_filter
+      label: Amounts Less Than
+      description: Number to filter on transactions with an amount less than this value
+      data_source:
+        table_or_query: "SELECT 0 as min_value, 300 as max_value, 10 as increment"
+        min_value_col: min_value
+        max_value_col: max_value
+        increment_col: increment                          ## optional, default is null
+        default_value_col: max_value                      ## optional, default is null
+        id_col: null                                      ## optional, shown is default - required for SingleSelect and MultiSelect, optional for others
+  
+  - type: NumberRangeParameter
+    factory: CreateWithOptions
+    arguments:
+      name: between_filter
+      label: Amounts Between
+      description: Number range to filter on transactions with an amount within this range
+      all_options:
+        - min_value: 0
+          max_value: 300
+          default_lower_value: 0                          ## optional, default is null (or min_value) - exists for NumberRange options only
+          default_upper_value: 300                        ## optional, default is null (or max_value) - exists for NumberRange options only
+
+

squirrels/_package_data/base_project/pyconfigs/connections.py

@@ -0,0 +1,19 @@
+from typing import Any
+from squirrels.arguments import ConnectionsArgs
+from squirrels.connections import ConnectionProperties, ConnectionTypeEnum
+
+
+def main(connections: dict[str, ConnectionProperties | Any], sqrl: ConnectionsArgs) -> None:
+    """
+    Define sqlalchemy engines by adding them to the "connections" dictionary
+    """
+    ## SQLAlchemy URL for a connection engine
+    conn_str: str = sqrl.env_vars["SQLITE_URI"].format(project_path=sqrl.project_path)
+
+    ## Assigning names to connection engines
+    connections["default"] = ConnectionProperties(
+        label="SQLite Expenses Database", 
+        type=ConnectionTypeEnum.SQLALCHEMY, 
+        uri=conn_str
+    )
+    

squirrels/_package_data/base_project/pyconfigs/context.py

@@ -0,0 +1,96 @@
+from typing import cast, Any
+from squirrels.arguments import ContextArgs
+from squirrels import parameters as p
+
+from pyconfigs.user import CustomUserFields
+
+
+def main(ctx: dict[str, Any], sqrl: ContextArgs) -> None:
+    """
+    Define context variables AFTER parameter selections are made by adding entries to the dictionary "ctx". 
+    These context variables can then be used in the models.
+
+    Note that the code here is used by all datasets, regardless of the parameters they use. You can use 
+    sqrl.param_exists to determine the conditions to execute certain blocks of code.
+    """
+    custom_fields = cast(CustomUserFields, sqrl.user.custom_fields)
+
+    if sqrl.param_exists("group_by"):
+        group_by_param = sqrl.prms["group_by"]
+        assert isinstance(group_by_param, p.SingleSelectParameter)
+        
+        selected_id = group_by_param.get_selected_id()
+        columns = group_by_param.get_selected("columns")
+        aliases = group_by_param.get_selected("aliases", default_field="columns")
+        assert isinstance(columns, list) and isinstance(aliases, list) and len(columns) == len(aliases)
+
+        column_to_alias_mapping = {x: y for x, y in zip(columns, aliases) if not y.startswith("_")}
+        order_by_cols = list(column_to_alias_mapping.values())
+
+        ctx["column_to_alias_mapping"] = column_to_alias_mapping
+        ctx["group_by_cols"] = order_by_cols if selected_id != "trans" else None
+
+        # Only used if federate_example is a Python model
+        mask_column = lambda x: x if custom_fields.role == "manager" else "***MASKED***"
+        ctx["order_by_cols"] = order_by_cols
+        ctx["mask_column_function"] = mask_column
+        
+        # Only used if federate_example is a SQL model
+        mask_column = lambda x: x if custom_fields.role == "manager" else "'***MASKED***'"
+        x_as_y = lambda x, y: (mask_column(x) if x in ["description"] else x)+" as "+y
+        ctx["select_dim_cols"] = list(x_as_y(x, y) for x, y in column_to_alias_mapping.items())
+        ctx["aggregator"] = "SUM" if selected_id != "trans" else ""
+        ctx["order_by_cols_desc"] = list(y+" DESC" for y in order_by_cols)
+        
+    if sqrl.param_exists("start_date"):
+        start_date_param = sqrl.prms["start_date"]
+        assert isinstance(start_date_param, p.DateParameter)
+
+        ctx["start_date"] = start_date_param.get_selected_date()
+    
+    if sqrl.param_exists("end_date"):
+        end_date_param = sqrl.prms["end_date"]
+        assert isinstance(end_date_param, p.DateParameter)
+
+        ctx["end_date"] = end_date_param.get_selected_date()
+
+    if sqrl.param_exists("date_range"):
+        date_range_param = sqrl.prms["date_range"]
+        assert isinstance(date_range_param, p.DateRangeParameter)
+
+        ctx["start_date_from_range"] = date_range_param.get_selected_start_date()
+        ctx["end_date_from_range"] = date_range_param.get_selected_end_date()
+    
+    if sqrl.param_exists("category"):
+        category_param = sqrl.prms["category"]
+        assert isinstance(category_param, p.MultiSelectParameter)
+
+        ctx["has_categories"] = category_param.has_non_empty_selection()
+        ctx["categories"] = category_param.get_selected_ids_as_list()
+    
+    if sqrl.param_exists("subcategory"):
+        subcategory_param = sqrl.prms["subcategory"]
+        assert isinstance(subcategory_param, p.MultiSelectParameter)
+
+        ctx["has_subcategories"] = subcategory_param.has_non_empty_selection()
+        ctx["subcategories"] = subcategory_param.get_selected_ids_as_list()
+    
+    if sqrl.param_exists("min_filter"):
+        min_amount_filter = sqrl.prms["min_filter"]
+        assert isinstance(min_amount_filter, p.NumberParameter)
+
+        ctx["min_amount"] = min_amount_filter.get_selected_value()
+    
+    if sqrl.param_exists("max_filter"):
+        max_amount_filter = sqrl.prms["max_filter"]
+        assert isinstance(max_amount_filter, p.NumberParameter)
+
+        ctx["max_amount"] = max_amount_filter.get_selected_value()
+
+    if sqrl.param_exists("between_filter"):
+        between_filter = sqrl.prms["between_filter"]
+        assert isinstance(between_filter, p.NumberRangeParameter)
+
+        ctx["min_amount_from_range"] = between_filter.get_selected_lower_value()
+        ctx["max_amount_from_range"] = between_filter.get_selected_upper_value()
+    

squirrels/_package_data/base_project/pyconfigs/parameters.py

@@ -0,0 +1,141 @@
+from squirrels import parameters as p, parameter_options as po, data_sources as ds
+
+
+## Example of creating SingleSelectParameter and specifying each option by code
+@p.SingleSelectParameter.create_with_options(
+    name="group_by", label="Group By", 
+    description="Dimension(s) to aggregate by", 
+    user_attribute="access_level"
+)
+def group_by_options():
+    return [
+        po.SelectParameterOption(
+            id="trans", label="Transaction",  
+            columns=["id","date","category","subcategory","description"],
+            aliases=["_id","date","category","subcategory","description"], # in context.py, any alias starting with "_" will not be selected
+            user_groups=["admin"]
+        ),
+        po.SelectParameterOption(
+            id="day", label="Day", 
+            columns=["date"], 
+            aliases=["day"], 
+            user_groups=["admin","member"]
+        ),
+        po.SelectParameterOption(
+            id="month", label="Month", 
+            columns=["month"], 
+            user_groups=["admin","member","guest"]
+        ),
+        po.SelectParameterOption(
+            id="cat", label="Category", 
+            columns=["category"], 
+            user_groups=["admin","member","guest"]
+        ),
+        po.SelectParameterOption(
+            id="subcat", label="Subcategory", 
+            columns=["category","subcategory"], 
+            user_groups=["admin","member","guest"]
+        ),
+    ]
+
+
+## Example of creating DateParameter
+@p.DateParameter.create_from_source(
+    name="start_date", label="Start Date", 
+    description="Start date to filter transactions by"
+)
+def start_date_source():
+    return ds.DateDataSource(
+        table_or_query="SELECT min(date) AS min_date, max(date) AS max_date FROM expenses",
+        default_date_col="min_date", 
+        min_date_col="min_date", max_date_col="max_date",
+    )
+
+
+## Example of creating DateParameter from list of DateParameterOption's
+@p.DateParameter.create_with_options(
+    name="end_date", label="End Date", 
+    description="End date to filter transactions by"
+)
+def end_date_options():
+    return [
+        po.DateParameterOption(
+            default_date="2024-12-31", min_date="2024-01-01", max_date="2024-12-31"
+        )
+    ]
+
+
+## Example of creating DateRangeParameter
+@p.DateRangeParameter.create_simple(
+    name="date_range", label="Date Range", 
+    default_start_date="2024-01-01", default_end_date="2024-12-31", 
+    min_date="2024-01-01", max_date="2024-12-31",
+    description="Date range to filter transactions by"
+)
+def date_range_options():
+    pass
+
+
+## Example of creating MultiSelectParameter from lookup query/table
+@p.MultiSelectParameter.create_from_source(
+    name="category", label="Category Filter", 
+    description="The expense categories to filter transactions by"
+)
+def category_source():
+    return ds.SelectDataSource(
+        table_or_query="seed_categories", 
+        id_col="category_id", 
+        options_col="category", 
+        source=ds.SourceEnum.SEEDS
+    )
+
+
+## Example of creating MultiSelectParameter with parent from lookup query/table
+@p.MultiSelectParameter.create_from_source(
+    name="subcategory", label="Subcategory Filter",
+    description="The expense subcategories to filter transactions by (available options are based on selected value(s) of 'Category Filter')", 
+    parent_name="category"
+)
+def subcategory_source():
+    return ds.SelectDataSource(
+        table_or_query="seed_subcategories", 
+        id_col="subcategory_id", 
+        options_col="subcategory", 
+        source=ds.SourceEnum.SEEDS, 
+        parent_id_col="category_id"
+    )
+
+
+## Example of creating NumberParameter
+@p.NumberParameter.create_simple(
+    name="min_filter", label="Amounts Greater Than", 
+    min_value=0, max_value=300, increment=10,
+    description="Number to filter on transactions with an amount greater than this value"
+)
+def min_filter_options():
+    pass
+
+
+## Example of creating NumberParameter from lookup query/table
+@p.NumberParameter.create_from_source(
+    name="max_filter", label="Amounts Less Than",
+    description="Number to filter on transactions with an amount less than this value"
+)
+def max_filter_source():
+    return ds.NumberDataSource(
+        table_or_query="SELECT 0 as min_value, 300 as max_value, 10 as increment",
+        min_value_col="min_value", max_value_col="max_value", 
+        increment_col="increment", 
+        default_value_col="max_value"
+    )
+
+
+## Example of creating NumberRangeParameter
+@p.NumberRangeParameter.create_simple(
+    name="between_filter", label="Amounts Between", 
+    min_value=0, max_value=300, 
+    default_lower_value=0, default_upper_value=300,
+    description="Number range to filter on transactions with an amount within this range"
+)
+def between_filter_options():
+    pass

squirrels/_package_data/base_project/pyconfigs/user.py

@@ -0,0 +1,56 @@
+from typing import Literal, Any
+from squirrels.auth import CustomUserFields as BaseCustomUserFields, ProviderConfigs, RegisteredUser, provider
+from squirrels.arguments import AuthProviderArgs
+
+
+class CustomUserFields(BaseCustomUserFields):
+    """
+    Extend the CustomUserFields class to add custom user attributes. 
+    - Only the following types are supported: [str, int, float, bool, typing.Literal]
+    - Add "| None" after the type to make it nullable. 
+    - Always set a default value for the field (use None if default is null).
+    
+    Example:
+        organization: str | None = None
+    """
+    role: Literal["manager", "staff", "customer"] = "staff"
+
+
+# @provider(
+#     name="google", label="Google", 
+#     icon="https://www.google.com/favicon.ico"
+#     # ^ Note: You also can save the google favicon as an image file in "resources/public/logos/google.ico" 
+#     #   and use icon="/public/logos/google.ico" instead
+# )
+def google_auth_provider(sqrl: AuthProviderArgs) -> ProviderConfigs:
+    """
+    Example provider configs for authenticating a user using Google credentials.
+
+    See the following page for setting up the CLIENT_ID and CLIENT_SECRET for Google specifically: 
+    - https://support.google.com/googleapi/answer/6158849?hl=en
+
+    IMPORTANT: Avoid using Google OAuth if you set auth_strategy to 'external'.
+    - If auth_strategy is 'external', MCP clients would require Dynamic Client Registration (DCR) to 
+      authenticate with the associated OAuth provider used by the Squirrels MCP server.
+    - Unfortunately, Google OAuth (and many other OAuth providers) do not support DCR. If auth_strategy 
+      is 'external', consider using an alternative that supports DCR instead (such as WorkOS or Keycloak).
+    """
+    def get_sqrl_user(claims: dict[str, Any]) -> RegisteredUser:
+        custom_fields = CustomUserFields(role="customer")
+        return RegisteredUser(
+            username=claims["email"],
+            access_level="member", # or "admin"
+            custom_fields=custom_fields
+        )
+
+    # TODO: Add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to the .env file
+    # Then, uncomment the @provider decorator above and set the client_id and client_secret below
+    provider_configs = ProviderConfigs(
+        client_id="", # sqrl.env_vars["GOOGLE_CLIENT_ID"],
+        client_secret="", # sqrl.env_vars["GOOGLE_CLIENT_SECRET"],
+        server_url="https://accounts.google.com",
+        client_kwargs={"scope": "openid email profile"},
+        get_user=get_sqrl_user
+    )
+
+    return provider_configs

squirrels/_package_data/base_project/seeds/seed_categories.csv

@@ -0,0 +1,6 @@
+"category_id","category"
+"0","Food"
+"1","Bills"
+"2","Shopping"
+"3","Transportation"
+"4","Entertainment"

squirrels/_package_data/base_project/seeds/seed_categories.yml

@@ -0,0 +1,15 @@
+description: |
+  Lookup table for the category IDs and names of transactions.
+
+cast_column_types: true  # optional, default is false - if set to true, then SQRL_SEEDS__INFER_SCHEMA is ignored for this seed
+
+columns:
+  - name: category_id
+    type: string
+    description: The category ID
+    category: dimension
+  
+  - name: category
+    type: string
+    description: The human-readable category name
+    category: dimension

squirrels/_package_data/base_project/seeds/seed_subcategories.csv

@@ -0,0 +1,15 @@
+"subcategory_id","subcategory","category_id"
+"0","Dining Out","0"
+"1","Groceries","0"
+"2","Utilities","1"
+"3","Electronics","2"
+"4","Ride Sharing","3"
+"5","Mobile","1"
+"6","Home Decor","2"
+"7","Internet","1"
+"8","Theater","4"
+"9","Movies","4"
+"10","Sports","2"
+"11","Public Transit","3"
+"12","Clothing","2"
+"13","Concerts","4"

squirrels/_package_data/base_project/seeds/seed_subcategories.yml

@@ -0,0 +1,21 @@
+description: |
+  Lookup table for the subcategory IDs and names of transactions.
+
+cast_column_types: true  # optional, default is false - if set to true, then SQRL_SEEDS__INFER_SCHEMA is ignored for this seed
+
+columns:
+  - name: subcategory_id
+    type: string
+    description: The subcategory ID
+    category: dimension
+  
+  - name: subcategory
+    type: string
+    description: The human-readable subcategory name
+    category: dimension
+  
+  - name: category_id
+    type: string
+    description: The category ID that the subcategory belongs to
+    category: dimension
+  

squirrels/_package_data/base_project/squirrels.yml.j2

@@ -0,0 +1,61 @@
+project_variables:
+  name: expenses
+  label: "Sample Expenses"
+  description: This is a sample Squirrels project for analyzing expense transactions
+  major_version: 1
+  auth_type: optional                     ## one of 'optional' (default) or 'required'
+
+
+packages: []
+
+## Example for packages section:
+# packages:
+#   - git: https://.../myrepo.git
+#     revision: v0.1.0
+#     directory: custom_name ## optional
+
+
+{{ connections -}}
+
+
+{{ parameters -}}
+
+
+datasets:
+  - name: expense_transactions
+    label: Expense Transactions - DBView Example
+    description: All expense transactions
+    model: dbview_example                 ## optional - if not specified, model name uses the dataset name
+    scope: private                        ## optional - one of 'public', 'protected', or 'private'. Default is 'public' (if auth_type is 'optional') or 'protected' (if auth_type is 'required').
+    parameters:                           ## optional - if not specified, then all parameters are used
+      - start_date
+      - end_date
+      - min_filter
+      - max_filter
+  
+  - name: grouped_expenses
+    label: Grouped Expenses - Federate Example
+    description: Aggregated expense transactions by custom dimension using federate_example model
+    model: federate_example
+    parameters:
+      - group_by
+      - date_range
+      - category
+      - subcategory
+      - between_filter
+
+
+selection_test_sets:
+  - name: set_start_date
+    parameters:                           ## optional section - if not provided, then default value is used for all parameters
+      start_date: 2024-07-01              ## this parameter is only used by model "dbview_example"
+  
+  - name: set_date_range
+    parameters:
+      date_range: [2024-02-01,2024-11-30] ## this parameter is only used by model "federate_example"
+    
+  - name: use_admin_privileged_group_by
+    user:
+      access_level: admin
+    parameters:
+      group_by: trans

squirrels/_package_data/base_project/tmp/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

squirrels/_package_data/templates/login_successful.html

@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Signed In</title>
+  <style>
+    body {
+      font-family: -apple-system, system-ui, sans-serif;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      height: 100vh;
+      margin: 0;
+      background-color: #f9fafb;
+      color: #111827;
+    }
+    .card {
+      text-align: center;
+      padding: 24px;
+    }
+    .icon {
+      color: #059669;
+      font-size: 48px;
+      margin-bottom: 16px;
+    }
+    h1 {
+      font-size: 24px;
+      font-weight: 600;
+      margin: 0 0 8px;
+    }
+    p {
+      font-size: 16px;
+      color: #6b7280;
+      margin: 0;
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="icon">✓</div>
+    <h1>Signed in successfully</h1>
+    <p>You can close this window now.</p>
+  </div>
+
+  <script>
+    if (window.opener) {
+      window.opener.postMessage({ type: "squirrels:auth:login-successful" }, "*");
+      setTimeout(function() { window.close(); }, 1000);
+    }
+  </script>
+</body>
+</html>

squirrels/_package_data/templates/squirrels_studio.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link id="favicon" rel="icon" type="image/svg+xml" href="{{ sqrl_studio_base_url }}/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Squirrels Studio</title>
+    <script>
+      // Optional: Set global defaults for project parameters
+      window.DEFAULT_MOUNTPATH = '{{ mount_path }}';
+    </script>
+    <!-- 
+      GitHub Pages serves static files with a Cache-Control header that typically tells the browser to cache for 10 minutes.
+      The implementation of squirrels-studio-v2 should be compatible with all versions of Squirrels from v0.6.0 onwards.
+    -->
+    <script type="module" crossorigin src="{{ sqrl_studio_base_url }}/assets/index.js"></script>
+    <link rel="stylesheet" crossorigin href="{{ sqrl_studio_base_url }}/assets/index.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>