create_notebook
Generate and customize Jupyter notebooks for Python and Markdown tasks, ensuring unique names and valid JSON content for streamlined data analysis and integration with SingleStore databases.
Instructions
Create a new Jupyter notebook in your personal space. Only supports python and markdown.
Parameters:
- notebook_name (required): Name for the new notebook
- Can include or omit .ipynb extension
- Must be unique in your personal space
- content (optional): JSON object with the following structure:
{
"cells": [
{"type": "markdown", "content": "Markdown content here"},
{"type": "code", "content": "Python code here"}
]
}
- 'type' must be either 'markdown' or 'code'
- 'content' is the text content of the cell
IMPORTANT: The content must be valid JSON.
How to use:
- Before creating the notebook, call check_if_file_exists tool to verify if the notebook already exists.
- Always install the dependencies on the first cell. Example:
{
"cells": [
{"type": "code", "content": "!pip install singlestoredb --quiet"},
// other cells...
]
}
- To connect to the database, use the variable "connection_url" that already exists in the notebook platform. Example:
{
"cells": [
{"type": "code", "content": "conn = s2.connect(connection_url)"},
// other cells...
]
}Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| ctx | No | ||
| notebook_name | Yes |
Implementation Reference
- Main handler function that creates a temporary Jupyter notebook (.ipynb) file from simplified content input, validates structure and schema, and returns the temp file path.
async def create_notebook_file(ctx: Context, content: Dict[str, Any]) -> Dict[str, Any]: """ Create a Jupyter notebook file in the correct singlestore format and saves it to a temporary location. This tool validates the provided content against the Jupyter notebook schema and creates a properly formatted .ipynb file in a temporary location. The content is converted from the simplified format to the full Jupyter notebook format. Args: content: Notebook content in the format: { "cells": [ {"type": "markdown", "content": "Markdown content here"}, {"type": "code", "content": "Python code here"} ] } Returns: Dictionary with the temporary file path and validation status Example: content = { "cells": [ {"type": "markdown", "content": "# My Notebook\nThis is a sample notebook"}, {"type": "code", "content": "import pandas as pd\nprint('Hello World')"} ] } """ settings = config.get_settings() user_id = config.get_user_id() settings.analytics_manager.track_event( user_id, "tool_calling", {"name": "create_notebook_file"}, ) start_time = time.time() try: # Validate content structure content_error = utils.validate_content_structure(content) if content_error: return content_error # Convert simplified format to full Jupyter notebook format notebook_cells, cells_error = utils.convert_to_notebook_cells(content["cells"]) if cells_error: return cells_error # Create full notebook structure notebook_content = utils.create_notebook_structure(notebook_cells) # Validate against Jupyter notebook schema schema_validated, schema_error = utils.validate_notebook_schema( notebook_content ) if schema_error: return schema_error # Create temporary file temp_file = tempfile.NamedTemporaryFile( mode="w", suffix=".ipynb", prefix="notebook_", delete=False, ) try: # Write notebook content to temporary file json.dump(notebook_content, temp_file, indent=2) temp_file_path = temp_file.name finally: temp_file.close() execution_time = (time.time() - start_time) * 1000 return { "status": "success", "message": "Notebook file created successfully at temporary location", "data": { "tempFilePath": temp_file_path, "cellCount": len(notebook_cells), "schemaValidated": schema_validated, "notebookFormat": {"nbformat": 4, "nbformat_minor": 5}, }, "metadata": { "executionTimeMs": round(execution_time, 2), "timestamp": datetime.now(timezone.utc).isoformat(), "tempFileSize": os.path.getsize(temp_file_path), }, } except Exception as e: logger.error(f"Error creating notebook file: {str(e)}") return { "status": "error", "message": f"Failed to create notebook file: {str(e)}", "errorCode": "NOTEBOOK_CREATION_FAILED", "errorDetails": {"exception_type": type(e).__name__}, } - src/api/tools/tools.py:31-50 (registration)Central registration of all tools, including create_notebook_file at position 14 in the tools_definition list.
tools_definition = [ {"func": get_user_info}, {"func": organization_info}, {"func": choose_organization}, {"func": set_organization}, {"func": workspace_groups_info}, {"func": workspaces_info}, {"func": resume_workspace}, {"func": list_starter_workspaces}, {"func": create_starter_workspace}, {"func": terminate_starter_workspace}, {"func": list_regions}, {"func": list_sharedtier_regions}, {"func": run_sql}, {"func": create_notebook_file}, {"func": upload_notebook_file}, {"func": create_job_from_notebook}, {"func": get_job}, {"func": delete_job}, ] - src/api/tools/tools.py:19-22 (registration)Import of the create_notebook_file function into the central tools module.
from src.api.tools.notebooks import ( create_notebook_file, upload_notebook_file, ) - Helper function called by the handler to build the full Jupyter notebook JSON structure from cells.
def create_notebook_structure(notebook_cells: list) -> Dict[str, Any]: """ Create the full Jupyter notebook structure. Returns: Complete notebook dictionary ready for serialization """ return { "nbformat": 4, "nbformat_minor": 5, "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3", }, "language_info": { "name": "python", "version": "3.8.0", "mimetype": "text/x-python", "codemirror_mode": {"name": "ipython", "version": 3}, "pygments_lexer": "ipython3", "file_extension": ".py", }, }, "cells": notebook_cells, } - Helper function to validate the generated notebook content against the Jupyter notebook schema loaded from notebook-schema.json.
def validate_notebook_schema( notebook_content: Dict[str, Any], ) -> tuple[bool, Optional[Dict[str, Any]]]: """ Validate notebook content against Jupyter notebook schema. Returns: Tuple of (schema_validated, error_dict). error_dict is None if successful or skipped. """ try: # Load schema from external file schema = get_notebook_schema() # Validate notebook content against schema jsonschema.validate(notebook_content, schema) logger.info("Notebook content validated successfully against schema file") return True, None except FileNotFoundError as e: logger.warning(f"Schema file not found: {str(e)}") # Continue without validation if schema file is missing return False, None except json.JSONDecodeError as e: logger.error(f"Invalid JSON in schema file: {str(e)}") return False, { "status": "error", "message": f"Schema file contains invalid JSON: {str(e)}\nPlease call create_notebook_file tool to create a jupyter notebook in the correct format", "errorCode": "INVALID_SCHEMA_FILE", "errorDetails": {"json_error": str(e)}, } except jsonschema.ValidationError as e: return False, { "status": "error", "message": f"Notebook content validation failed: {e.message}", "errorCode": "SCHEMA_VALIDATION_FAILED", "errorDetails": {"validation_error": str(e)}, } except Exception as e: logger.warning(f"Schema validation failed: {str(e)}") # Continue without validation if schema can't be loaded return False, None