{"id":33235873,"url":"https://github.com/obiedeh/ai-ran-kpi-forecasting","last_synced_at":"2026-05-30T16:31:16.322Z","repository":{"id":357959159,"uuid":"1101103462","full_name":"obiedeh/ai-ran-kpi-forecasting","owner":"obiedeh","description":"AI-RAN KPI forecasting system for RAN telemetry, operational intelligence, and network performance analysis.","archived":false,"fork":false,"pushed_at":"2026-05-21T22:53:16.000Z","size":927,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T07:52:45.256Z","etag":null,"topics":["ai-for-ran","ai-ran","forecasting","kpi","kpi-forecasting","network-operations","non-rt-ric","oran","ran-telemetry","rapp","telemetry","time-series"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/obiedeh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":"2025-11-21T07:41:31.000Z","updated_at":"2026-05-21T22:53:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/obiedeh/ai-ran-kpi-forecasting","commit_stats":null,"previous_names":["obiedeh/ai-ran-kpi-forecasting"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/obiedeh/ai-ran-kpi-forecasting","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obiedeh%2Fai-ran-kpi-forecasting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obiedeh%2Fai-ran-kpi-forecasting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obiedeh%2Fai-ran-kpi-forecasting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obiedeh%2Fai-ran-kpi-forecasting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/obiedeh","download_url":"https://codeload.github.com/obiedeh/ai-ran-kpi-forecasting/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obiedeh%2Fai-ran-kpi-forecasting/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33700863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-for-ran","ai-ran","forecasting","kpi","kpi-forecasting","network-operations","non-rt-ric","oran","ran-telemetry","rapp","telemetry","time-series"],"created_at":"2025-11-16T18:01:12.804Z","updated_at":"2026-05-30T16:31:16.315Z","avatar_url":"https://github.com/obiedeh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI-RAN KPI Forecasting - Non-RT RIC rApp Pattern\n\n## One-line summary\n\nA reproducible Non-RT RIC rApp pattern for AI-for-RAN KPI forecasting: KPM-style telemetry in, forward-looking KPI forecasts out, advisory A1 policy candidates generated, and static evidence dashboards published for review.\n\nThis is not a claim of a deployed RIC application. It is a reproducible engineering pattern with typed contracts, no-leakage forecasting, scenario evidence, and explicit deployment boundaries.\n\n\u003e **▶ [Open the live evidence portal](https://obiedeh.github.io/ai-ran-kpi-forecasting/reports/index.html)** · [Dashboard](https://obiedeh.github.io/ai-ran-kpi-forecasting/reports/dashboard.html) · [Tech brief](TECH_BRIEF.md) · [Data contract](DATA_CONTRACT.md) · [Project status](PROJECT_STATUS.md)\n\n## Why this exists\n\nRAN operations cannot rely only on after-the-fact dashboards. The practical question is whether a non-real-time intelligence layer can see KPI degradation early enough to recommend a policy review before the cell is already in trouble.\n\nFrom an engineering standpoint, I built this as a bridge between telecom KPI analytics and the way AI-for-RAN work is expected to be packaged: contracts, evidence, policy boundaries, and reproducible artifacts. A forecasting model alone is not enough signal.\n\nThe Non-RT RIC / rApp model is the relevant O-RAN architectural pattern for this class of non-real-time RAN intelligence: telemetry-driven analytics, forecasting, policy recommendation, and model lifecycle support. This repo implements that pattern on synthetic/sample telemetry; integration with FlexRIC, OSC RIC, or a vendor RIC is documented but not exercised.\n\n## What problem it solves\n\nThis project asks a more operational question than “can a model forecast a KPI?” It asks whether a Non-RT intelligence layer can package forecast evidence, scenario impact, and an advisory A1 policy candidate in a way an engineer could inspect before taking action.\n\n## The engineering pattern\n\n```mermaid\nflowchart LR\n    A[\"KPM-style telemetry\"] --\u003e B[\"Schema and data contract\"]\n    B --\u003e C[\"Temporal feature pipeline\"]\n    C --\u003e D[\"Ridge / GBR / MLP model comparison\"]\n    D --\u003e E[\"Forward KPI forecast\"]\n    E --\u003e F[\"Advisory A1 policy candidate\"]\n    F --\u003e G[\"Static dashboard and scenario evidence\"]\n    G --\u003e H[\"Operator review\"]\n```\n\n## Live evidence portal\n\n- [Live evidence portal](https://obiedeh.github.io/ai-ran-kpi-forecasting/reports/index.html)\n- [Live dashboard](https://obiedeh.github.io/ai-ran-kpi-forecasting/reports/dashboard.html)\n- [Published local portal](reports/publish/latest/index.html)\n- [Scenario dashboards](reports/scenarios/latest/)\n\nGitHub shows committed HTML files as source code. Use the GitHub Pages links above to open the rendered pages.\n\n## Headline evidence\n\n| Signal | Value | Source |\n|---|---|---|\n| KPM-style input contract | shipped | `schemas/kpm_input_v1.json` |\n| Advisory A1 output contract | shipped | `schemas/a1_policy_v1.json` |\n| rApp packaging signal | shipped | `rapp_manifest.yaml` |\n| Three-model comparison | Ridge 0.8368 RMSE, GBR 2.8755 RMSE, MLP 22.5926 RMSE | `reports/model_comparison/comparison_metrics.md` |\n| Sample forecast metrics | RMSE 0.8368, MAE 0.6954, MAPE 0.8204% | `reports/forecast_examples/latest/metrics.json` |\n| R1-style dataflow demo | KPM-style input to forecast to A1 candidate | `reports/r1_dataflow_demo/` |\n| Scenario evidence | congestion, backhaul saturation, cell outage | `reports/scenarios/latest/` |\n| Telecom Italia MI benchmark | Benchmark-ready: pending local public dataset files. No benchmark metric claimed yet. | `reports/forecast_examples/telecom_italia_mi/` |\n| Reproducibility | `make verify` regenerates committed evidence artifacts | `Makefile` |\n\n## What makes this more than a forecasting notebook\n\n- Temporal evaluation: train/test splits preserve time order; no shuffled leakage.\n- Operational feature design: lag features use only past KPI values available at inference time.\n- Typed RAN telemetry contract: `schemas/kpm_input_v1.json` defines the KPM-style input boundary.\n- Typed policy output contract: `schemas/a1_policy_v1.json` defines the advisory A1 candidate boundary.\n- rApp packaging signal: `rapp_manifest.yaml` documents identity, inputs, outputs, and integration expectations.\n- Scenario evidence: congestion, backhaul saturation, and cell outage reports connect forecasts to operator action.\n- Reproducibility: `make verify` regenerates committed evidence artifacts.\n- Honest boundary: no live RIC deployment, no autonomous control, no production policy enforcement.\n\n## Architecture\n\nThe architecture is documented in [docs/architecture.md](docs/architecture.md), with Mermaid diagrams under [docs/diagrams/](docs/diagrams/).\n\nThe core runtime path is:\n\n```text\nKPM-style telemetry -\u003e validation and feature generation -\u003e temporal forecasting\n-\u003e advisory A1 policy candidate -\u003e report artifacts -\u003e operator review\n```\n\n## Dashboard and report artifacts\n\n| Artifact | Purpose |\n|---|---|\n| `reports/index.html` | GitHub Pages evidence portal |\n| `reports/dashboard.html` | top-level operational dashboard generated with the portal |\n| `reports/forecast_examples/latest/metrics.json` | sample forecast metrics |\n| `reports/model_comparison/comparison_metrics.md` | Ridge / GBR / MLP comparison |\n| `reports/r1_dataflow_demo/a1_policy_candidate.json` | advisory A1 policy candidate |\n| `reports/scenarios/latest/` | congestion, backhaul, and outage evidence packs |\n| `reports/publish/latest/index.html` | release-friendly landing page |\n\n## Measured results\n\nThe committed measured results use deterministic sample telemetry, not live operator data.\n\n| Measurement | Result | Boundary |\n|---|---:|---|\n| Sample PRB forecast RMSE | 0.8368 | ridge baseline on `data/ran_kpi_sample.csv` |\n| Sample PRB forecast MAE | 0.6954 | same sample, same temporal split |\n| Sample PRB forecast MAPE | 0.8204% | small sample metric only |\n| Gradient boosting RMSE | 2.8755 | weaker on current sample |\n| MLP RMSE | 22.5926 | underfits current sample |\n\nThe small-data result is intentionally visible: Ridge wins here. The model is the least interesting part of the repo; the useful part is the engineering boundary around the model. The public Telecom Italia MI path exists to test whether model ranking changes on a larger dataset.\n\n## Benchmark readiness: Telecom Italia MI\n\nThe repo includes a public benchmark path for the Telecom Italia Milan dataset, but the dataset is not committed because of size and licensing/distribution constraints.\n\nCurrent status:\n\n- Loader path: `ai_ran_kpi_forecasting.data.load_telecom_italia_mi`\n- Make target: `make run-telecom`\n- Output target: `reports/forecast_examples/telecom_italia_mi/`\n- Published result: Benchmark-ready: pending local public dataset files. No benchmark metric claimed yet.\n\nTo run when data is available:\n\n```bash\nmake run-telecom REPORT_DIR=reports/forecast_examples/telecom_italia_mi\ncat reports/forecast_examples/telecom_italia_mi/metrics.json\n```\n\nUntil that artifact exists, this repo does not claim Telecom Italia MI benchmark accuracy.\n\n## GitHub repo description\n\nRecommended description:\n\n\u003e Non-RT RIC rApp pattern for AI-RAN KPI forecasting, scenario evidence, and advisory A1 policy generation.\n\n## Credibility boundary\n\nThis repo demonstrates a Non-RT RIC rApp pattern for AI-for-RAN KPI forecasting on synthetic and small sample telemetry. The boundary is not a weakness; it is what keeps the evidence useful. It does not claim:\n\n- live RAN integration\n- live Non-RT RIC deployment\n- operator validation\n- E2, A1, O1, or R1 wire-protocol implementation\n- autonomous network control\n- closed-loop policy enforcement\n- production rApp lifecycle or service registration\n\nThe deliverable is the pattern, contracts, model comparison, and evidence pack.\n\n## Quickstart\n\n```bash\ngit clone https://github.com/obiedeh/ai-ran-kpi-forecasting.git\ncd ai-ran-kpi-forecasting\npython -m venv .venv\nsource .venv/bin/activate\nmake install-dev\nmake run-sample\ncat reports/forecast_examples/latest/metrics.json\n```\n\nWindows / direct Python:\n\n```powershell\npython -m venv .venv\n.\\.venv\\Scripts\\activate\npip install -r requirements.txt -r requirements-dev.txt\npython ai-ran-kpi-forecasting.py run-sample --output-dir reports/forecast_examples/latest\npython ai-ran-kpi-forecasting.py portal --output reports/index.html\n```\n\n## Reproduce all artifacts\n\n```bash\nmake verify\n```\n\n`make verify` runs lint, tests, sample forecast, model comparison, R1 dataflow demo, scenario dashboards, portal generation, and publish-page generation.\n\n## Repository map\n\n```text\nconfigs/                         sample run configuration\ndata/                            committed sample telemetry\ndocs/                            architecture and AI-RAN integration notes\nreports/                         committed evidence artifacts and HTML pages\nschemas/                         KPM input and advisory A1 policy contracts\nscripts/                         model comparison and R1 dataflow demo scripts\nsrc/ai_ran_kpi_forecasting/       package source\ntests/                           unit and pipeline tests\nrapp_manifest.yaml               rApp identity, inputs, outputs, and boundary\n```\n\n## Engineering signal\n\nThis project is designed around the operational shape of an AI-for-RAN workflow, not just model accuracy. The core signal is the boundary discipline around the model: typed telemetry input, time-ordered evaluation, scenario evidence, advisory policy output, and explicit limits around deployment.\n\n- Temporal evaluation is used instead of shuffled train/test splits, so the forecast is tested closer to how it would behave in operation.\n- KPM-style input and A1 advisory output are defined as typed contracts, making the system boundaries inspectable.\n- Forecast outputs are connected to advisory policy candidates instead of being left as standalone charts.\n- Weak model results remain visible in the evidence pack, because hiding them would make the evaluation less credible.\n- The Telecom Italia MI benchmark path is prepared, but no benchmark result is claimed until the dataset is run locally.\n- The HTML evidence pack is generated and GitHub Pages compatible, so results can be reviewed without cloning the repo.\n\n## Next engineering steps\n\nThe next steps are intentionally narrow: improve evidence quality before adding integration complexity.\n\n1. Run the Telecom Italia MI benchmark locally and publish the measured metrics.\n2. Extend the workflow to multi-cell batch forecasting while preserving temporal evaluation and no-leakage feature rules.\n3. Add drift and retraining-readiness reports so the project reflects an operational AI lifecycle.\n4. Add a real Non-RT RIC adapter only when there is a target OSC RIC, FlexRIC, or vendor RIC environment to test against.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobiedeh%2Fai-ran-kpi-forecasting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobiedeh%2Fai-ran-kpi-forecasting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobiedeh%2Fai-ran-kpi-forecasting/lists"}