squirrels 0.5.0b4__tar.gz → 0.5.1__tar.gz

{squirrels-0.5.0b4 → squirrels-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: squirrels
-Version: 0.5.0b4
+Version: 0.5.1
 Summary: Squirrels - API Framework for Data Analytics
 Project-URL: Homepage, https://squirrels-analytics.github.io
 Project-URL: Repository, https://github.com/squirrels-analytics/squirrels
@@ -15,8 +15,8 @@ Classifier: Typing :: Typed
 Requires-Python: ~=3.10
 Requires-Dist: authlib<2,>=1.5.2
 Requires-Dist: bcrypt<5,>=4.0.1
-Requires-Dist: cachetools<6,>=5.3.2
-Requires-Dist: duckdb<2,>=1.1.3
+Requires-Dist: cachetools>=5.3.2
+Requires-Dist: duckdb<2,>=1.4.0
 Requires-Dist: fastapi<1,>=0.112.1
 Requires-Dist: gitpython<4,>=3.1.41
 Requires-Dist: inquirer<4,>=3.2.1
@@ -24,8 +24,7 @@ Requires-Dist: itsdangerous<3,>=2.2.0
 Requires-Dist: jinja2<4,>=3.1.3
 Requires-Dist: libpass<2,>=1.9.0
 Requires-Dist: matplotlib<4,>=3.8.3
-Requires-Dist: mcp>=1.9.2
-Requires-Dist: networkx<4,>=3.2.1
+Requires-Dist: mcp>=1.13.1
 Requires-Dist: pandas<3,>=2.1.4
 Requires-Dist: polars<2,>=1.14.0
 Requires-Dist: pyarrow>=19.0.1
@@ -51,22 +50,38 @@ Squirrels is an API framework that lets you create REST APIs for dynamic data an
 
 - [Main Features](#main-features)
 - [License](#license)
-- [Contributing to squirrels](#contributing-to-squirrels)
+- [Contributing to Squirrels](#contributing-to-squirrels)
     - [Setup](#setup)
     - [Testing](#testing)
     - [Project Structure](#project-structure)
 
 ## Main Features
 
-Here are a few of the things that squirrels can do:
+Here are a few of the things that Squirrels can do:
 
 - Connect to any database by specifying its SQLAlchemy url (in `squirrels.yml`) or by using its native connector library in python (in `connections.py`).
 - Configure API routes for datasets (in `squirrels.yml`) without writing code.
 - Configure parameter widgets (types include single-select, multi-select, date, number, etc.) for your datasets (in `parameters.py`).
-- Use Jinja SQL templates (just like dbt!) or python functions (that return a Python dataframe such as polars or pandas) to define dynamic query logic based on parameter selections.
+- Use SQL templates (templated with Jinja, like dbt) or python functions (that return a Python dataframe in polars or pandas) to define dynamic query logic based on parameter selections.
 - Query multiple databases and join the results together in a final view in one API endpoint/dataset!
-- Test your API endpoints with Squirrels Studio or by a command line that generates rendered sql queries and results (for a given set of parameter selections).
+- Test your API endpoints with Squirrels Studio or by a command line that generates rendered sql queries and results as files (for a given set of parameter selections).
 - Define User model (in `user.py`) and authorize privacy scope per dataset (in `squirrels.yml`). The user's attributes can even be used in your query logic!
+- Serve dataset metadata and results to AI agents via MCP (Model Context Protocol)
+
+## Quick Start
+
+In a new virtual environment, install `squirrels`. Then, in your project directory, activate the virtual environment and run the following commands:
+
+```bash
+sqrl new --use-defaults --curr-dir
+sqrl build
+```
+
+To run the API server, simply run:
+
+```bash
+sqrl run
+```
 
 ## License
 
@@ -74,9 +89,9 @@ Squirrels is released under the Apache 2.0 license.
 
 See the file LICENSE for more details.
 
-## Contributing to squirrels
+## Contributing to Squirrels
 
-The sections below describe how to set up your local environment for squirrels development and run unit tests. A high level overview of the project structure is also provided.
+The sections below describe how to set up your local environment for Squirrels development and run unit tests. A high level overview of the project structure is also provided.
 
 ### Setup
 
@@ -94,7 +109,7 @@ And activate the virtual environment with:
 source .venv/bin/activate
 ```
 
-To confirm that the setup worked, run the following to show the help page for all squirrels CLI commands:
+To confirm that the setup worked, run the following to show the help page for all Squirrels CLI commands:
 
 ```bash
 sqrl -h
@@ -108,6 +123,6 @@ Run `uv run pytest`. Or if you have the virtual environment activated, simply ru
 
 From the root of the git repo, the source code can be found in the `squirrels` folder and unit tests can be found in the `tests` folder.
 
-To understand what a specific squirrels command is doing, start from the `_command_line.py` file as your entry point.
+To understand what a specific Squirrels command is doing, start from the `_command_line.py` file as your entry point.
 
 The library version is maintained in both the `pyproject.toml` and the `squirrels/_version.py` files.

{squirrels-0.5.0b4 → squirrels-0.5.1}/README.md

@@ -10,22 +10,38 @@ Squirrels is an API framework that lets you create REST APIs for dynamic data an
 
 - [Main Features](#main-features)
 - [License](#license)
-- [Contributing to squirrels](#contributing-to-squirrels)
+- [Contributing to Squirrels](#contributing-to-squirrels)
     - [Setup](#setup)
     - [Testing](#testing)
     - [Project Structure](#project-structure)
 
 ## Main Features
 
-Here are a few of the things that squirrels can do:
+Here are a few of the things that Squirrels can do:
 
 - Connect to any database by specifying its SQLAlchemy url (in `squirrels.yml`) or by using its native connector library in python (in `connections.py`).
 - Configure API routes for datasets (in `squirrels.yml`) without writing code.
 - Configure parameter widgets (types include single-select, multi-select, date, number, etc.) for your datasets (in `parameters.py`).
-- Use Jinja SQL templates (just like dbt!) or python functions (that return a Python dataframe such as polars or pandas) to define dynamic query logic based on parameter selections.
+- Use SQL templates (templated with Jinja, like dbt) or python functions (that return a Python dataframe in polars or pandas) to define dynamic query logic based on parameter selections.
 - Query multiple databases and join the results together in a final view in one API endpoint/dataset!
-- Test your API endpoints with Squirrels Studio or by a command line that generates rendered sql queries and results (for a given set of parameter selections).
+- Test your API endpoints with Squirrels Studio or by a command line that generates rendered sql queries and results as files (for a given set of parameter selections).
 - Define User model (in `user.py`) and authorize privacy scope per dataset (in `squirrels.yml`). The user's attributes can even be used in your query logic!
+- Serve dataset metadata and results to AI agents via MCP (Model Context Protocol)
+
+## Quick Start
+
+In a new virtual environment, install `squirrels`. Then, in your project directory, activate the virtual environment and run the following commands:
+
+```bash
+sqrl new --use-defaults --curr-dir
+sqrl build
+```
+
+To run the API server, simply run:
+
+```bash
+sqrl run
+```
 
 ## License
 
@@ -33,9 +49,9 @@ Squirrels is released under the Apache 2.0 license.
 
 See the file LICENSE for more details.
 
-## Contributing to squirrels
+## Contributing to Squirrels
 
-The sections below describe how to set up your local environment for squirrels development and run unit tests. A high level overview of the project structure is also provided.
+The sections below describe how to set up your local environment for Squirrels development and run unit tests. A high level overview of the project structure is also provided.
 
 ### Setup
 
@@ -53,7 +69,7 @@ And activate the virtual environment with:
 source .venv/bin/activate
 ```
 
-To confirm that the setup worked, run the following to show the help page for all squirrels CLI commands:
+To confirm that the setup worked, run the following to show the help page for all Squirrels CLI commands:
 
 ```bash
 sqrl -h
@@ -67,6 +83,6 @@ Run `uv run pytest`. Or if you have the virtual environment activated, simply ru
 
 From the root of the git repo, the source code can be found in the `squirrels` folder and unit tests can be found in the `tests` folder.
 
-To understand what a specific squirrels command is doing, start from the `_command_line.py` file as your entry point.
+To understand what a specific Squirrels command is doing, start from the `_command_line.py` file as your entry point.
 
 The library version is maintained in both the `pyproject.toml` and the `squirrels/_version.py` files.

{squirrels-0.5.0b4 → squirrels-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "squirrels"
-version = "0.5.0b4"
+version = "0.5.1"
 description = "Squirrels - API Framework for Data Analytics"
 authors = [{ name = "Tim Huang", email = "tim.yuting@hotmail.com" }]
 requires-python = "~=3.10"
@@ -13,13 +13,12 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "cachetools>=5.3.2,<6",
+    "cachetools>=5.3.2",
     "fastapi>=0.112.1,<1",
     "gitpython>=3.1.41,<4",
     "inquirer>=3.2.1,<4",
     "jinja2>=3.1.3,<4",
     "matplotlib>=3.8.3,<4",
-    "networkx>=3.2.1,<4",
     "pandas>=2.1.4,<3",
     "pydantic>=2.8.2,<3",
     "pyjwt>=2.8.0,<3",
@@ -29,14 +28,14 @@ dependencies = [
     "uvicorn>=0.30.6,<1",
     "polars>=1.14.0,<2",
     "pyarrow>=19.0.1",
-    "duckdb>=1.1.3,<2",
+    "duckdb>=1.4.0,<2",
     "sqlglot>=26.12.1",
     "bcrypt>=4.0.1,<5",
     "python-dotenv>=1.0.1,<2",
     "libpass>=1.9.0,<2",
     "authlib>=1.5.2,<2",
     "itsdangerous>=2.2.0,<3",
-    "mcp>=1.9.2",
+    "mcp>=1.13.1",
 ]
 
 [project.urls]
@@ -49,16 +48,16 @@ squirrels = "squirrels._command_line:main"
 sqrl = "squirrels._command_line:main"
 
 [dependency-groups]
-test = ["pytest>=7.4.4,<8"]
+test = ["pytest>=7.4.4"]
 dev = [
-    "ipykernel>=6.29.4,<7",
-    "plotly>=5.24.0,<6",
-    "psycopg2-binary>=2.9.10,<3",
-    "adbc-driver-postgresql>=1.3.0,<2",
-    "adbc-driver-sqlite>=1.3.0,<2",
-    "connectorx>=0.4.0,<0.5",
-    "faker>=33.1.0,<34",
-    "tqdm>=4.67.1,<5",
+    "ipykernel>=6.29.4",
+    "plotly>=5.24.0",
+    "psycopg2-binary>=2.9.10",
+    "adbc-driver-postgresql>=1.3.0",
+    "adbc-driver-sqlite>=1.3.0",
+    "connectorx>=0.4.0",
+    "faker>=33.1.0",
+    "tqdm>=4.67.1",
 ]
 
 [tool.hatch.build.targets.sdist]

{squirrels-0.5.0b4 → squirrels-0.5.1}/squirrels/__init__.py

@@ -17,3 +17,5 @@ from .dashboards import *
 from .types import *
 
 from ._project import SquirrelsProject
+
+__all__ = ["SquirrelsProject"]

{squirrels-0.5.0b4 → squirrels-0.5.1}/squirrels/_api_routes/auth.py

@@ -1,17 +1,16 @@
 """
 Authentication and user management routes
 """
-from typing import Annotated, Callable
+from typing import Annotated, Literal
 from fastapi import FastAPI, Depends, Request, Response, status, Form, APIRouter
 from fastapi.responses import RedirectResponse
 from fastapi.security import HTTPBearer
 from pydantic import BaseModel, Field
 from authlib.integrations.starlette_client import OAuth
 
-from .. import _constants as c
 from .._schemas import response_models as rm
 from .._exceptions import InvalidInputError
-from .._auth import BaseUser
+from .._schemas.auth_models import AbstractUser, RegisteredUser, GuestUser
 from .base import RouteBase
 
 
@@ -21,18 +20,19 @@ class AuthRoutes(RouteBase):
     def __init__(self, get_bearer_token: HTTPBearer, project, no_cache: bool = False):
         super().__init__(get_bearer_token, project, no_cache)
         
-    def setup_routes(self, app: FastAPI) -> None:
+    def setup_routes(self, app: FastAPI, squirrels_version_path: str) -> None:
         """Setup all authentication routes"""
 
-        auth_router = APIRouter(prefix="/api/auth")
-        user_management_router = APIRouter(prefix="/api/auth/user-management")
+        auth_path = squirrels_version_path + "/auth"
+        auth_router = APIRouter(prefix=auth_path)
+        user_management_router = APIRouter(prefix=auth_path + "/user-management")
         
         # Get expiry configuration
         expiry_mins = self._get_access_token_expiry_minutes()
         
         # Create user models
-        class UpdateUserModel(self.UserModel):
-            is_admin: bool
+        class UpdateUserModel(self.authenticator.CustomUserFields):
+            access_level: Literal["admin", "member"]
 
         class UserInfoModel(UpdateUserModel):
             username: str
@@ -54,14 +54,15 @@ class AuthRoutes(RouteBase):
 
         # User info endpoint
         @auth_router.get("/userinfo", description="Get the authenticated user's fields", tags=["Authentication"])
-        async def get_userinfo(user: UserInfoModel | None = Depends(self.get_current_user)) -> UserInfoModel:
-            if user is None:
-                raise InvalidInputError(401, "Invalid authorization token", "Invalid authorization token")
-            return user
+        async def get_userinfo(user: RegisteredUser | GuestUser = Depends(self.get_current_user)) -> UserInfoModel:
+            if isinstance(user, GuestUser):
+                raise InvalidInputError(401, "invalid_authorization_token", "Invalid authorization token, no user info found")
+            custom_fields = user.custom_fields.model_dump(mode='json')
+            return UserInfoModel(username=user.username, access_level=user.access_level, **custom_fields)
 
         # Login helper
         def login_helper(
-            request: Request, user: BaseUser, redirect_url: str | None, *, 
+            request: Request, user: RegisteredUser, redirect_url: str | None, *, 
             redirect_status_code: int = status.HTTP_307_TEMPORARY_REDIRECT
         ):
             access_token, expiry = self.authenticator.create_access_token(user, expiry_minutes=expiry_mins)
@@ -75,6 +76,8 @@ class AuthRoutes(RouteBase):
             302: {"description": "Redirect if redirect URL parameter is specified"},
         })
         async def login(request: Request, username: Annotated[str, Form()], password: Annotated[str, Form()], redirect_url: str | None = None):
+            if self.manifest_cfg.authentication.type.value == "external":
+                raise InvalidInputError(403, "forbidden_login", "Username/password login is disabled when authentication.type is 'external'")
             user = self.authenticator.get_user(username, password)
             return login_helper(request, user, redirect_url, redirect_status_code=status.HTTP_302_FOUND)
         
@@ -83,10 +86,10 @@ class AuthRoutes(RouteBase):
             307: {"description": "Redirect if redirect URL parameter is specified"},
         })
         async def login_with_api_key(
-            request: Request, redirect_url: str | None = None, user: UserInfoModel | None = Depends(self.get_current_user)
+            request: Request, redirect_url: str | None = None, user: RegisteredUser | GuestUser = Depends(self.get_current_user)
         ):
-            if user is None:
-                raise InvalidInputError(401, "Invalid authorization token", "Invalid authorization token")
+            if isinstance(user, GuestUser):
+                raise InvalidInputError(401, "invalid_authorization_token", "Invalid authorization token, no user info found")
             return login_helper(request, user, redirect_url)
         
         # Provider authentication endpoints
@@ -109,7 +112,7 @@ class AuthRoutes(RouteBase):
 
         @auth_router.get(provider_login_path, tags=["Authentication"])
         async def provider_login(request: Request, provider_name: str, redirect_url: str | None = None) -> RedirectResponse:
-            """Get OAuth login URL for the provider"""
+            """Redirect to the login URL for the OAuth provider"""
             client = oauth.create_client(provider_name)
             if client is None:
                 raise InvalidInputError(status_code=404, error="provider_not_found", error_description=f"Provider {provider_name} not found or configured.")
@@ -159,22 +162,23 @@ class AuthRoutes(RouteBase):
             302: {"description": "Redirect if redirect URL parameter is specified"},
         })
         async def logout(request: Request, redirect_url: str | None = None):
+            """Logout the current user, and redirect to the specified URL if provided"""
             request.session.pop("access_token", None)
             request.session.pop("access_token_expiry", None)
             if redirect_url:
                 return RedirectResponse(url=redirect_url)
         
         # Change password endpoint
-        change_password_path = '/change-password'
+        change_password_path = '/password'
 
         class ChangePasswordRequest(BaseModel):
             old_password: str
             new_password: str
 
         @auth_router.put(change_password_path, description="Change the password for the current user", tags=["Authentication"])
-        async def change_password(request: ChangePasswordRequest, user: UserInfoModel | None = Depends(self.get_current_user)) -> None:
-            if user is None:
-                raise InvalidInputError(401, "Invalid authorization token", "Invalid authorization token")
+        async def change_password(request: ChangePasswordRequest, user: RegisteredUser | GuestUser = Depends(self.get_current_user)) -> None:
+            if isinstance(user, GuestUser):
+                raise InvalidInputError(401, "invalid_authorization_token", "Invalid authorization token")
             self.authenticator.change_password(user.username, request.old_password, request.new_password)
 
         # API Key endpoints
@@ -188,17 +192,17 @@ class AuthRoutes(RouteBase):
             )
 
         @auth_router.post(api_key_path, description="Create a new API key for the user", tags=["Authentication"])
-        async def create_api_key(body: ApiKeyRequestBody, user: UserInfoModel | None = Depends(self.get_current_user)) -> rm.ApiKeyResponse:
-            if user is None:
-                raise InvalidInputError(401, "Invalid authorization token", "Invalid authorization token")
+        async def create_api_key(body: ApiKeyRequestBody, user: RegisteredUser | GuestUser = Depends(self.get_current_user)) -> rm.ApiKeyResponse:
+            if isinstance(user, GuestUser):
+                raise InvalidInputError(401, "invalid_authorization_token", "Invalid authorization token, cannot create API key")
             
             api_key, _ = self.authenticator.create_access_token(user, expiry_minutes=body.expiry_minutes, title=body.title)
             return rm.ApiKeyResponse(api_key=api_key)
         
         @auth_router.get(api_key_path, description="Get all API keys with title for the current user", tags=["Authentication"])
-        async def get_all_api_keys(user: UserInfoModel | None = Depends(self.get_current_user)):
-            if user is None:
-                raise InvalidInputError(401, "Invalid authorization token", "Invalid authorization token")
+        async def get_all_api_keys(user: RegisteredUser | GuestUser = Depends(self.get_current_user)):
+            if isinstance(user, GuestUser):
+                raise InvalidInputError(401, "invalid_authorization_token", "Invalid authorization token, cannot get API keys")
             return self.authenticator.get_all_api_keys(user.username)
         
         revoke_api_key_path = '/api-key/{api_key_id}'
@@ -206,57 +210,62 @@ class AuthRoutes(RouteBase):
         @auth_router.delete(revoke_api_key_path, description="Revoke an API key", tags=["Authentication"], responses={
             204: { "description": "API key revoked successfully" }
         })
-        async def revoke_api_key(api_key_id: str, user: UserInfoModel | None = Depends(self.get_current_user)) -> Response:
-            if user is None:
-                raise InvalidInputError(401, "Invalid authorization token", "Invalid authorization token")
+        async def revoke_api_key(api_key_id: str, user: RegisteredUser | GuestUser = Depends(self.get_current_user)) -> Response:
+            if isinstance(user, GuestUser):
+                raise InvalidInputError(401, "invalid_authorization_token", "Invalid authorization token, cannot revoke API key")
             self.authenticator.revoke_api_key(user.username, api_key_id)
             return Response(status_code=204)
 
-        # User management endpoints
-        user_fields_path = '/user-fields'
+        # User management endpoints (disabled if external auth only)
+        if self.manifest_cfg.authentication.type.value == "managed":
+            user_fields_path = '/user-fields'
 
-        @user_management_router.get(user_fields_path, description="Get details of the user fields", tags=["User Management"])
-        async def get_user_fields():
-            return self.authenticator.user_fields
-        
-        add_user_path = '/users'
-
-        @user_management_router.post(add_user_path, description="Add a new user by providing details for username, password, and user fields", tags=["User Management"])
-        async def add_user(
-            new_user: AddUserModel, user: UserInfoModel | None = Depends(self.get_current_user)
-        ) -> None:
-            if user is None or not user.is_admin:
-                raise InvalidInputError(403, "Forbidden to add user", "Authorized user is forbidden to add new users")
-            self.authenticator.add_user(new_user.username, new_user.model_dump(mode='json', exclude={"username"}))
-
-        update_user_path = '/users/{username}'
-
-        @user_management_router.put(update_user_path, description="Update the user of the given username given the new user details", tags=["User Management"])
-        async def update_user(
-            username: str, updated_user: UpdateUserModel, user: UserInfoModel | None = Depends(self.get_current_user)
-        ) -> None:
-            if user is None or not user.is_admin:
-                raise InvalidInputError(403, "Forbidden to update user", "Authorized user is forbidden to update users")
-            self.authenticator.add_user(username, updated_user.model_dump(mode='json'), update_user=True)
-
-        list_users_path = '/users'
-
-        @user_management_router.get(list_users_path, tags=["User Management"])
-        async def list_all_users():
-            return self.authenticator.get_all_users()
-        
-        delete_user_path = '/users/{username}'
-
-        @user_management_router.delete(delete_user_path, tags=["User Management"], responses={
-            204: { "description": "User deleted successfully" }
-        })
-        async def delete_user(username: str, user: UserInfoModel | None = Depends(self.get_current_user)) -> Response:
-            if user is None or not user.is_admin:
-                raise InvalidInputError(403, "Forbidden to delete user", "Authorized user is forbidden to delete users")
-            if username == user.username:
-                raise InvalidInputError(403, "Cannot delete your own user", "Cannot delete your own user")
-            self.authenticator.delete_user(username)
-            return Response(status_code=204)
+            @user_management_router.get(user_fields_path, description="Get details of the user fields", tags=["User Management"])
+            async def get_user_fields():
+                return self.authenticator.user_fields
+            
+            add_user_path = '/users'
+
+            @user_management_router.post(add_user_path, description="Add a new user by providing details for username, password, and user fields", tags=["User Management"])
+            async def add_user(
+                new_user: AddUserModel, user: AbstractUser = Depends(self.get_current_user)
+            ) -> None:
+                if user.access_level != "admin":
+                    raise InvalidInputError(403, "unauthorized_to_add_user", "Current user cannot add new users")
+                self.authenticator.add_user(new_user.username, new_user.model_dump(mode='json', exclude={"username"}))
+
+            update_user_path = '/users/{username}'
+
+            @user_management_router.put(update_user_path, description="Update the user of the given username given the new user details", tags=["User Management"])
+            async def update_user(
+                username: str, updated_user: UpdateUserModel, user: AbstractUser = Depends(self.get_current_user)
+            ) -> None:
+                if user.access_level != "admin":
+                    raise InvalidInputError(403, "unauthorized_to_update_user", "Current user cannot update users")
+                self.authenticator.add_user(username, updated_user.model_dump(mode='json'), update_user=True)
+
+            list_users_path = '/users'
+
+            @user_management_router.get(list_users_path, tags=["User Management"])
+            async def list_all_users() -> list[UserInfoModel]:
+                registered_users = self.authenticator.get_all_users()
+                return [
+                    UserInfoModel(username=user.username, access_level=user.access_level, **user.custom_fields.model_dump(mode='json')) 
+                    for user in registered_users
+                ]
+            
+            delete_user_path = '/users/{username}'
+
+            @user_management_router.delete(delete_user_path, tags=["User Management"], responses={
+                204: { "description": "User deleted successfully" }
+            })
+            async def delete_user(username: str, user: AbstractUser = Depends(self.get_current_user)) -> Response:
+                if user.access_level != "admin":
+                    raise InvalidInputError(403, "unauthorized_to_delete_user", "Current user cannot delete users")
+                if username == user.username:
+                    raise InvalidInputError(403, "cannot_delete_own_user", "Cannot delete your own user")
+                self.authenticator.delete_user(username)
+                return Response(status_code=204)
 
         app.include_router(auth_router)
         app.include_router(user_management_router)