{"id":24332567,"url":"https://github.com/frequenz-floss/frequenz-lib-notebooks","last_synced_at":"2025-09-27T18:31:56.388Z","repository":{"id":272420590,"uuid":"916102311","full_name":"frequenz-floss/frequenz-lib-notebooks","owner":"frequenz-floss","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-14T09:45:16.000Z","size":721,"stargazers_count":0,"open_issues_count":7,"forks_count":1,"subscribers_count":2,"default_branch":"v0.x.x","last_synced_at":"2025-01-14T10:53:47.197Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frequenz-floss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-13T13:12:42.000Z","updated_at":"2025-01-14T09:37:16.000Z","dependencies_parsed_at":"2025-01-14T10:53:56.819Z","dependency_job_id":"22d42ba3-7fb8-43a6-9df7-cba35bb0d920","html_url":"https://github.com/frequenz-floss/frequenz-lib-notebooks","commit_stats":null,"previous_names":["frequenz-floss/frequenz-lib-notebooks"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Ffrequenz-lib-notebooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Ffrequenz-lib-notebooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Ffrequenz-lib-notebooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Ffrequenz-lib-notebooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frequenz-floss","download_url":"https://codeload.github.com/frequenz-floss/frequenz-lib-notebooks/tar.gz/refs/heads/v0.x.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234453466,"owners_count":18835044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-18T02:28:50.880Z","updated_at":"2025-09-27T18:31:56.376Z","avatar_url":"https://github.com/frequenz-floss.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tooling Library for Notebooks\n\n[![Build Status](https://github.com/frequenz-floss/frequenz-lib-notebooks/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-lib-notebooks/actions/workflows/ci.yaml)\n[![PyPI Package](https://img.shields.io/pypi/v/frequenz-lib-notebooks)](https://pypi.org/project/frequenz-lib-notebooks/)\n[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-lib-notebooks/)\n\n## Introduction\n\nA modular Python toolkit designed to support notebook-based workflows. It provides reusable tools for data ingestion, transformations, visualisation, notifications, and microgrid metadata managers. These tools make the repository ideal for streamlining analytics workflows with minimal setup and building data pipelines, reporting workflows, and alert systems seamlessly in Jupyter or cloud notebooks.\n\n## Supported Platforms\n\nThe following platforms are officially supported (tested):\n\n- **Python:** 3.11\n- **Operating System:** Ubuntu Linux 20.04\n- **Architectures:** amd64, arm64\n\n## Contributing\n\nIf you want to know how to build this project and contribute to it, please\ncheck out the [Contributing Guide](CONTRIBUTING.md).\n\n## Quick Start\n\nInstall the package, open the example notebooks, and explore the available modules.\n\n### Installation\n\n```\n# Choose the version you want to install\nVERSION=0.9.2\npip install frequenz‑lib‑notebooks==$VERSION\n```\n\nThen open the prebuilt example notebooks using your preferred interface:\n- Classic Notebook: `jupyter examples/`\n- JupyterLab: `jupyter-lab examples/`\n\n⚠️ **Note**: This project does **not** install `jupyter` or `jupyterlab` by default. You will need to install it separately if you want to run notebooks:\n\n```\npip install jupyterlab\n```\n\n### Code Examples\n\n#### 📧 Example 1: Generate an Alert Email (HTML Body Only)\n\nThis example shows how to:\n- Transform a `pandas` DataFrame of alert records into a structured HTML email using `generate_alert_email`.\n- Use `AlertEmailConfig` to control layout (e.g., table row limits, sorting by severity).\n- Integrate microgrid-component alerts cleanly into operational workflows (e.g., for notifications or reporting tools).\n\n```\nimport pandas as pd\nfrom IPython.display import HTML\n\nfrom frequenz.lib.notebooks.alerts.alert_email import (\n    AlertEmailConfig,\n    generate_alert_email,\n)\nfrom frequenz.lib.notebooks.notification_utils import format_email_preview\n\n# Example alert records dataframe\nalert_records = pd.DataFrame(\n    [\n        {\n            \"microgrid_id\": 1,\n            \"component_id\": 1,\n            \"state_type\": \"error\",\n            \"state_value\": \"UNDERVOLTAGE\",\n            \"start_time\": \"2025-03-14 15:06:30\",\n            \"end_time\": \"2025-03-14 17:00:00\",\n        },\n        {\n            \"microgrid_id\": 2,\n            \"component_id\": 1,\n            \"state_type\": \"state\",\n            \"state_value\": \"DISCHARGING\",\n            \"start_time\": \"2025-03-14 15:06:30\",\n            \"end_time\": None,\n        },\n    ]\n)\n\n# Configuration for email generation\nalert_email_config = AlertEmailConfig(\n    displayed_rows=10,\n    sort_by_severity=True,\n)\n\n# Generate the HTML body of the alert email\nhtml_email = generate_alert_email(\n    alert_records=alert_records, config=alert_email_config\n)\n\n# Output the HTML # or send it via email as shown in the next example\nprint(html_email)\n\n# or preview it in a nicer format\nHTML(format_email_preview(subject=\"Alert Notification\", body_html=html_email))\n```\n\n#### 📨 Example 2: Compose and Send Alert Email with Attachments\nContinuing from Example 1, this snippet builds on the generated HTML email and demonstrates:\n\n- Configuring SMTP credentials and recipients.\n- Attaching both a CSV export of the alert data and optional visual plots.\n- Sending the email once or scheduling it periodically. Note that the periodic scheduling would make sense when the data also refreshes so as to not send the same email over and over again!\n\n```\nimport time\nfrom datetime import datetime\n\nfrom frequenz.lib.notebooks.alerts.alert_email import ExportOptions, plot_alerts\nfrom frequenz.lib.notebooks.notification_service import (\n    EmailConfig,\n    EmailNotification,\n    SchedulerConfig,\n)\n\n# Configuration for email notification\nemail_config = EmailConfig(\n    subject=\"Critical Alert\",\n    message=html_email,  # Assuming that html_email already exists. See the code example above on how to generate this.\n    recipients=[\"recipient@example.com\"],\n    smtp_server=\"smtp.example.com\",\n    smtp_port=587,\n    smtp_user=\"user@example.com\",\n    smtp_password=\"password\",\n    from_email=\"alert@example.com\",\n    scheduler=SchedulerConfig(\n        send_immediately=True,\n        interval=60,  # send every minute\n        duration=3600,  # for one hour total\n    ),\n)\n# The SMTP details and sender/recipient details need to be adjusted accordingly\n# note that the library provides a convenient way to validate the settings via frequenz.lib.notebooks.notification_utils.validate_email_config\n\n# Create a notification object\nemail_notification = EmailNotification(config=email_config)\n\n# optionally add attachments (a list of files)\nemail_config.attachments = None\ntimestamp = datetime.now().strftime(\"%Y%m%d_%H%M%S\")\nalert_file_name = f\"alert_details_{timestamp}.csv\"\nalert_records.to_csv(alert_file_name, index=False)\nemail_config.attachments = [alert_file_name]\n\n# Optionally create a visualisation of the alert records\nimg_path = plot_alerts(\n    records=alert_records,\n    plot_type=\"all\",\n    export_options=ExportOptions(\n        format=\"png\",\n        show=True,\n    ),\n)\nemail_config.attachments += img_path if img_path else []\n\n# Send one-off notification\nemail_notification.send()\n\n# Or start a periodic scheduler:\nemail_notification.start_scheduler()\ntime.sleep(300)  # let it run for 5 minutes\nemail_notification.stop_scheduler()\n```\n\n##  Module Overview\n\n- **Solar Maintenance App:** Interactive forecasting and visualisation tools tailored to solar installations.\n- **Notification Service:** Flexible and configurable email dispatching.\n- **Alert Email Generation:** Embed rich Plotly charts into alert emails, complete with context and summaries.\n- **Microgrid Configuration:** Manage structured microgrid metadata—location, devices, etc. — consistently across notebooks.\n\nFor more details about each module/project, please refer to the overview `Wiki` [page](https://github.com/frequenz-floss/frequenz-lib-notebooks/wiki/Frequenz-Lib-Notebooks-%E2%80%90-Overview) which has links to dedicated project pages.\n\nThe full code documentation can be accessed [here](https://frequenz-floss.github.io/frequenz-lib-notebooks/latest/).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrequenz-floss%2Ffrequenz-lib-notebooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrequenz-floss%2Ffrequenz-lib-notebooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrequenz-floss%2Ffrequenz-lib-notebooks/lists"}