{"id":41110956,"url":"https://github.com/frequenz-floss/frequenz-cs-reporting","last_synced_at":"2026-02-13T16:56:20.942Z","repository":{"id":333676126,"uuid":"1138239574","full_name":"frequenz-floss/frequenz-cs-reporting","owner":"frequenz-floss","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-21T11:31:05.000Z","size":4150,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T06:49:26.771Z","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-20T12:20:34.000Z","updated_at":"2026-01-21T11:25:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/frequenz-floss/frequenz-cs-reporting","commit_stats":null,"previous_names":["frequenz-floss/frequenz-cs-reporting"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/frequenz-floss/frequenz-cs-reporting","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Ffrequenz-cs-reporting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Ffrequenz-cs-reporting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Ffrequenz-cs-reporting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Ffrequenz-cs-reporting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frequenz-floss","download_url":"https://codeload.github.com/frequenz-floss/frequenz-cs-reporting/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Ffrequenz-cs-reporting/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28847149,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T15:15:36.453Z","status":"ssl_error","status_checked_at":"2026-01-28T15:15:13.020Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-01-22T15:55:49.346Z","updated_at":"2026-01-28T17:10:59.437Z","avatar_url":"https://github.com/frequenz-floss.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Frequenz CS Reporting Library\n\n[![Build Status](https://github.com/frequenz-floss/frequenz-cs-reporting/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-cs-reporting/actions/workflows/ci.yaml)\n[![PyPI Package](https://img.shields.io/pypi/v/frequenz-cs-reporting)](https://pypi.org/project/frequenz-cs-reporting/)\n[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-cs-reporting/)\n\n## Overview\n\nStreamlit library that ships a ready-to-use client reporting UI. It fetches data from the Frequenz reporting API, applies the energy\nreporting utilities from `frequenz-lib-notebooks`, and renders dashboards, tables, and plots with reusable Streamlit components.\n\n## Features\n\n- Pre-built Streamlit app with navigation, landing page, and reporting view.\n- Connects to the Frequenz reporting API to fetch microgrid measurements.\n- Ready-made dashboards (metrics, plots, and tables) powered by\n  `frequenz-lib-notebooks`.\n- Reusable components (sidebar filters, charts, tables) for your own pages.\n\n## Quick start\n\n1. Install the library (Python 3.12):\n   ```bash\n   pip install \"frequenz-cs-reporting\"\n   ```\n2. Provide environment variables (see below). A `.env` file works with Streamlit:\n   ```bash\n   REPORTING_API_URL=https://your-reporting-endpoint\n   API_KEY=your-api-key\n   API_SECRET=your-api-secret\n   MICROGRID_CONFIG_DIR=toml_directory/\n   ```\n3. Add .toml files to the toml_directory.\n4. Run the bundled UI from the repo root:\n   ```bash\n   streamlit run app.py\n   ```\n   Use the sidebar to pick a microgrid, date range, timezone, and resolution.\n\n## Configuration\n\n### Environment\n\n- `REPORTING_API_URL` **(required)**: Base URL for the Frequenz reporting API.\n- `API_KEY` and `API_SECRET` **(required)**: Credentials used by the data client.\n- `MICROGRID_CONFIG_DIR` *(optional)*: Directory containing TOML microgrid\n  configs. Defaults to `toml_directory/`.\n\n### Microgrid configs\n\nMicrogrid definitions are loaded from TOML files in `MICROGRID_CONFIG_DIR`.\n\n## Running the Streamlit app\n\nThe app entry point is `app.py`. When you run `streamlit run app.py`, it:\n\n- Discovers pages from `frequenz.cs_reporting.app_pages` (the default\n  build ships `Home` and `Reporting` pages).\n- Loads microgrid configs from `MICROGRID_CONFIG_DIR` and lists available IDs.\n- Fetches data via the reporting API.\n\n### Running in Deepnote\n- Running in Deepnote is supported; required environment variables can be injected\nvia the Deepnote integration.\n- Add this library as a requirement in requirements.txt\n- Add the docker image from dockerhub (currently named: CS-Reporting in deepnote).\n- Copy the app.py to the folder structure in Deepnote.\n- Click on create_streamlit_application in Deepnote UI to create the app.\n\n## Library usage\n\nFetch microgrid data programmatically (sync wrapper shown):\n\n```python\nfrom datetime import datetime, timedelta\nfrom frequenz.cs_reporting.services.data_service import get_microgrid_data\n\ndf = get_microgrid_data(\n    microgrid_id=241,\n    start_date=datetime(2024, 1, 1),\n    end_date=datetime(2024, 1, 2),\n    resolution=timedelta(minutes=15),\n)\n```\n\nBuild your own Streamlit page and add it to the navigation by defining a\n`PageSpec` in `frequenz.cs_reporting.app_pages`:\n\n```python\n# app_pages/custom.py\nfrom frequenz.cs_reporting.rep_cs_core.page_spec import PageSpec\nimport streamlit as st\n\ndef render() -\u003e None:\n    st.title(\"Custom view\")\n    st.write(\"Add your own charts or tables here.\")\n\nPAGE = PageSpec(key=\"custom\", title=\"Custom\", icon=\"🛠️\", order=10, render=render)\n```\n\n## Development\n\n- Install dev tools: `pip install -e \".[dev]\"`.\n- Run tests: `nox -l` to see sessions, e.g. `nox -s tests`.\n- Build docs with MkDocs (`README.md` is the landing page). After installing the\n  mkdocs extra you can use the `docs` nox session (if available) or run\n  `mkdocs serve`.\n\n## Supported Platforms\n\nThe following platforms are officially supported (tested):\n\n- **Python:** 3.12\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrequenz-floss%2Ffrequenz-cs-reporting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrequenz-floss%2Ffrequenz-cs-reporting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrequenz-floss%2Ffrequenz-cs-reporting/lists"}