runspec-grafana-core 0.1.0__tar.gz

runspec_grafana_core-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_grafana_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog — runspec-grafana-core
+
+## [0.1.0]
+
+First release. Pure-Python helpers over the Grafana HTTP API, ported from the
+read tools of the [Grafana MCP server](https://github.com/grafana/mcp-grafana)
+(no runspec dependency, no runnables). Results are compact by default:
+
+- **Identity and search:** `whoami`, `health`, `search_dashboards`,
+  `search_folders`.
+- **Dashboards:** `get_dashboard` returns a summary (folder, tags, variables,
+  one row per panel, rows unpacked); `include=["queries"]` adds each panel's
+  query text and datasource, `panel_id` narrows to one panel, `version` loads a
+  saved version, `raw=True` returns the API response. `list_dashboard_versions`
+  handles both the list and the Grafana 12 `{"versions": [...]}` shapes.
+- **Datasources:** `list_datasources`, `get_datasource` (secrets named, never
+  shown), `check_datasources` (health checks, failures reported not raised),
+  and `resolve_datasource`, which takes a UID or a name, or picks the default
+  (or only) datasource of a type when none is given.
+- **Prometheus through Grafana:** `query_prometheus` (instant or range; range
+  results summarised per series unless `include_values`),
+  `query_prometheus_histogram` (builds the `histogram_quantile` query),
+  `list_prometheus_metric_names` (with a regex filter),
+  `list_prometheus_label_names`, `list_prometheus_label_values`,
+  `list_prometheus_metric_metadata`.
+- **Loki through Grafana:** `query_loki_logs` (lines newest first, stream
+  labels listed once, each line cut to `max_line_chars`; metric queries
+  summarised), `list_loki_label_names`, `list_loki_label_values`,
+  `query_loki_stats`, `query_loki_patterns`.
+- **Alerting:** `list_alert_rules` (firing first, counts by state, Grafana-managed
+  or a datasource's own rules, only active alert instances counted),
+  `get_alert_rule`, `list_contact_points`, `list_silences`.
+- **Annotations:** `get_annotations`, `get_annotation_tags`, `create_annotation`.
+- `api_get`: GET any `/api/` path for what the helpers don't cover.
+- Queries go through the datasource proxy, retried through the plugin's
+  `/resources` route on 401/403/404/500/502, so only the Grafana token is needed.
+- `GrafanaConfig` / `config_from_env`: `GRAFANA_URL` (default
+  `http://127.0.0.1:3000`), `GRAFANA_SERVICE_ACCOUNT_TOKEN` (or `TOKEN`, `PAT`,
+  `API_KEY`) or basic `GRAFANA_USERNAME`/`GRAFANA_PASSWORD`, `GRAFANA_ORG_ID`,
+  `GRAFANA_CA_BUNDLE`, `GRAFANA_TLS_VERIFY`, `GRAFANA_PROXY`, with free-form
+  `GRAFANA_<ENV>_*` prefixes.
+- Times accept Unix seconds or milliseconds, RFC 3339, `now-1h`, or a duration
+  back from now.

runspec_grafana_core-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: runspec-grafana-core
+Version: 0.1.0
+Summary: Pure-Python Grafana HTTP API helpers — the importable core behind runspec-grafana (no runspec dependency, no runnables)
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'

runspec_grafana_core-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-grafana-core"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Pure-Python Grafana HTTP API helpers — the importable core behind runspec-grafana (no runspec dependency, no runnables)"
+dependencies = [
+    "httpx",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff==0.15.20",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_grafana_core-0.1.0/runspec_grafana_core/__init__.py

@@ -0,0 +1,113 @@
+"""runspec-grafana-core — pure-Python Grafana HTTP API helpers.
+
+This package depends only on ``httpx`` — it has **no dependency on runspec** and
+ships **no runspec.toml and no entry points**, so installing it exposes the
+helpers for import without surfacing any runnables (it is invisible to
+``runspec local`` / ``runspec serve`` discovery). ``runspec-grafana`` depends on
+it and wraps each helper as a verb of the ``grafana`` runnable.
+
+The helpers port the read tools of the Grafana MCP server
+(https://github.com/grafana/mcp-grafana) onto the Grafana HTTP API: dashboards,
+datasources, PromQL and LogQL through the datasource proxy, alert rules,
+silences, contact points, and annotations. Every operation takes an explicit
+:class:`GrafanaConfig` first argument, so a private wrapper package can inject
+credentials, bake in an instance or org, and build narrower runnables on top.
+Each function returns plain, compact data; failures raise :class:`GrafanaError`.
+"""
+
+from runspec_grafana_core.alerting import RULE_INCLUDE_OPTIONS, RULE_STATES, SILENCE_STATES, get_alert_rule, list_alert_rules, list_contact_points, list_silences
+from runspec_grafana_core.annotations import ANNOTATION_TYPES, create_annotation, get_annotation_tags, get_annotations
+from runspec_grafana_core.api import api_get, parse_params
+from runspec_grafana_core.client import (
+    DEFAULT_URL,
+    GrafanaConfig,
+    GrafanaError,
+    config_from_env,
+    datasource_request,
+    grafana_request,
+    parse_duration,
+    parse_time,
+)
+from runspec_grafana_core.dashboards import (
+    DASHBOARD_INCLUDE_OPTIONS,
+    dashboard_summary,
+    get_dashboard,
+    health,
+    list_dashboard_versions,
+    panel_queries,
+    search_dashboards,
+    search_folders,
+    whoami,
+)
+from runspec_grafana_core.datasources import check_datasources, fetch_datasource, get_datasource, list_datasources, resolve_datasource
+from runspec_grafana_core.loki import compact_streams, list_loki_label_names, list_loki_label_values, query_loki_logs, query_loki_patterns, query_loki_stats
+from runspec_grafana_core.prometheus import (
+    compact_series,
+    histogram_query,
+    list_prometheus_label_names,
+    list_prometheus_label_values,
+    list_prometheus_metric_metadata,
+    list_prometheus_metric_names,
+    query_prometheus,
+    query_prometheus_histogram,
+)
+
+__all__ = [
+    # client / config
+    "GrafanaConfig",
+    "GrafanaError",
+    "config_from_env",
+    "grafana_request",
+    "datasource_request",
+    "parse_time",
+    "parse_duration",
+    "DEFAULT_URL",
+    # identity / search / dashboards
+    "whoami",
+    "health",
+    "search_dashboards",
+    "search_folders",
+    "get_dashboard",
+    "dashboard_summary",
+    "panel_queries",
+    "list_dashboard_versions",
+    "DASHBOARD_INCLUDE_OPTIONS",
+    # datasources
+    "list_datasources",
+    "get_datasource",
+    "fetch_datasource",
+    "resolve_datasource",
+    "check_datasources",
+    # prometheus via grafana
+    "query_prometheus",
+    "query_prometheus_histogram",
+    "histogram_query",
+    "compact_series",
+    "list_prometheus_metric_names",
+    "list_prometheus_label_names",
+    "list_prometheus_label_values",
+    "list_prometheus_metric_metadata",
+    # loki via grafana
+    "query_loki_logs",
+    "compact_streams",
+    "list_loki_label_names",
+    "list_loki_label_values",
+    "query_loki_stats",
+    "query_loki_patterns",
+    # alerting
+    "list_alert_rules",
+    "get_alert_rule",
+    "list_contact_points",
+    "list_silences",
+    "RULE_STATES",
+    "RULE_INCLUDE_OPTIONS",
+    "SILENCE_STATES",
+    # annotations
+    "get_annotations",
+    "get_annotation_tags",
+    "create_annotation",
+    "ANNOTATION_TYPES",
+    # escape hatch
+    "api_get",
+    "parse_params",
+]

runspec_grafana_core-0.1.0/runspec_grafana_core/alerting.py

@@ -0,0 +1,192 @@
+"""alerting.py — alert rules with their live state, contact points, and silences.
+
+Rule state comes from Grafana's Prometheus-compatible rules endpoint
+(``/api/prometheus/grafana/api/v1/rules``, or a datasource's own rules with
+``datasource``); a rule's full definition from the provisioning API.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from runspec_grafana_core.client import GrafanaConfig, GrafanaError, drop_empty, grafana_request, preview, truncate
+from runspec_grafana_core.datasources import fetch_datasource
+
+RULE_STATES = ("firing", "pending", "inactive", "error", "nodata")
+RULE_INCLUDE_OPTIONS = ("alerts", "query", "annotations")
+SILENCE_STATES = ("active", "pending", "expired", "any")
+
+
+def _is_active(alert: dict[str, Any]) -> bool:
+    # Grafana lists every instance, Normal ones included ("Normal",
+    # "Normal (MissingSeries)"); Prometheus rulers list only pending/firing.
+    return not str(alert.get("state") or "").lower().startswith(("normal", "inactive"))
+
+
+def _rule_row(rule: dict[str, Any], group: dict[str, Any], include: list[str]) -> dict[str, Any]:
+    alerts = [a for a in rule.get("alerts") or [] if isinstance(a, dict) and _is_active(a)]
+    error, _ = preview(rule.get("lastError"), 300)
+    row: dict[str, Any] = drop_empty(
+        {
+            "uid": rule.get("uid"),
+            "name": rule.get("name"),
+            "state": rule.get("state"),
+            "health": rule.get("health"),
+            "folder": group.get("file"),
+            "group": group.get("name"),
+            "labels": rule.get("labels"),
+            "last_error": error,
+            "last_evaluation": rule.get("lastEvaluation"),
+        }
+    )
+    row["active_alerts"] = len(alerts)
+    if "query" in include and rule.get("query"):
+        row["query"] = rule["query"]
+    if "annotations" in include and rule.get("annotations"):
+        row["annotations"] = rule["annotations"]
+    if "alerts" in include and alerts:
+        row["alerts"] = [drop_empty({"labels": a.get("labels"), "state": a.get("state"), "active_at": a.get("activeAt"), "value": a.get("value")}) for a in alerts[:10]]
+    return row
+
+
+def list_alert_rules(
+    config: GrafanaConfig,
+    state: str | None = None,
+    search: str | None = None,
+    folder: str | None = None,
+    datasource: str | None = None,
+    include: list[str] | None = None,
+    limit: int | None = 100,
+) -> dict[str, Any]:
+    """Alert rules and their current state, firing first.
+
+    ``state`` keeps one of firing/pending/inactive/error/nodata (matched
+    against state or health); ``search`` is a case-insensitive substring of
+    the rule name; ``folder`` matches the folder title. ``datasource`` reads a
+    Prometheus/Loki datasource's own (ruler) rules instead of Grafana-managed
+    ones. ``include`` adds ``alerts`` (up to 10 active ones per rule), ``query``,
+    ``annotations``.
+    """
+    include = list(include or [])
+    unknown = sorted(set(include) - set(RULE_INCLUDE_OPTIONS))
+    if unknown:
+        raise GrafanaError(f"Unknown include part(s): {', '.join(unknown)} — choose from {', '.join(RULE_INCLUDE_OPTIONS)}")
+    if state and state not in RULE_STATES:
+        raise GrafanaError(f"state must be one of {', '.join(RULE_STATES)}")
+    source = "grafana"
+    if datasource:
+        source = str(fetch_datasource(config, datasource).get("uid"))
+    body = grafana_request("GET", f"/api/prometheus/{quote(source, safe='')}/api/v1/rules", config=config) or {}
+    if isinstance(body, dict) and body.get("status") == "error":
+        raise GrafanaError(f"Grafana rules: {body.get('error', 'unknown error')}")
+    groups = ((body.get("data") or {}) if isinstance(body, dict) else {}).get("groups") or []
+    rows = []
+    for group in groups:
+        if folder and (group.get("file") or "").lower() != folder.lower():
+            continue
+        for rule in group.get("rules") or []:
+            if not isinstance(rule, dict) or rule.get("type", "alerting") != "alerting":
+                continue
+            if search and search.lower() not in (rule.get("name") or "").lower():
+                continue
+            if state and state not in ((rule.get("state") or "").lower(), (rule.get("health") or "").lower()):
+                continue
+            rows.append(_rule_row(rule, group, include))
+    order = {"firing": 0, "pending": 1}
+    rows.sort(key=lambda r: (order.get(str(r.get("state")).lower(), 2), r.get("folder") or "", r.get("name") or ""))
+    counts: dict[str, int] = {}
+    for row in rows:
+        counts[str(row.get("state"))] = counts.get(str(row.get("state")), 0) + 1
+    kept, cut = truncate(rows, limit)
+    return {"count": len(rows), "by_state": counts, "truncated": cut, "rules": kept}
+
+
+def get_alert_rule(config: GrafanaConfig, uid: str, raw: bool = False) -> dict[str, Any]:
+    """A Grafana-managed alert rule's definition by UID: condition, queries,
+    labels, annotations, pending period, no-data/error handling."""
+    rule = grafana_request("GET", f"/api/v1/provisioning/alert-rules/{quote(uid, safe='')}", config=config) or {}
+    if raw:
+        return rule
+    queries = []
+    for item in rule.get("data") or []:
+        model = item.get("model") or {}
+        queries.append(
+            drop_empty(
+                {
+                    "ref_id": item.get("refId"),
+                    "datasource_uid": item.get("datasourceUid"),
+                    "query": model.get("expr") or model.get("expression") or model.get("query"),
+                    "type": model.get("type") if item.get("datasourceUid") == "__expr__" else None,
+                    "range": item.get("relativeTimeRange"),
+                }
+            )
+        )
+    return drop_empty(
+        {
+            "uid": rule.get("uid"),
+            "title": rule.get("title"),
+            "folder_uid": rule.get("folderUID"),
+            "rule_group": rule.get("ruleGroup"),
+            "condition": rule.get("condition"),
+            "for": rule.get("for"),
+            "labels": rule.get("labels"),
+            "annotations": rule.get("annotations"),
+            "no_data_state": rule.get("noDataState"),
+            "exec_err_state": rule.get("execErrState"),
+            "is_paused": rule.get("isPaused") or None,
+            "updated": rule.get("updated"),
+            "queries": queries,
+        }
+    )
+
+
+def list_contact_points(config: GrafanaConfig, name: str | None = None, include_settings: bool = False, limit: int | None = 100) -> dict[str, Any]:
+    """Notification contact points: ``[{uid, name, type, settings?}]``. Grafana
+    redacts secret settings (webhook URLs, keys) unless the token may read them."""
+    items = [c for c in grafana_request("GET", "/api/v1/provisioning/contact-points", config=config, params={"name": name}) or [] if isinstance(c, dict)]
+    rows = []
+    for c in items:
+        row = drop_empty({"uid": c.get("uid"), "name": c.get("name"), "type": c.get("type"), "disable_resolve_message": c.get("disableResolveMessage") or None})
+        if include_settings and c.get("settings"):
+            row["settings"] = c["settings"]
+        rows.append(row)
+    kept, cut = truncate(rows, limit)
+    return {"count": len(rows), "truncated": cut, "contact_points": kept}
+
+
+def _matchers(matchers: list[dict[str, Any]]) -> str:
+    """Silence matchers as PromQL-style text: ``alertname="X", job=~"api.*"``."""
+    ops = {(True, False): "=", (False, False): "!=", (True, True): "=~", (False, True): "!~"}
+    out = []
+    for m in matchers:
+        op = ops[(m.get("isEqual") is not False, bool(m.get("isRegex")))]
+        out.append(f'{m.get("name")}{op}"{m.get("value")}"')
+    return ", ".join(out)
+
+
+def list_silences(config: GrafanaConfig, state: str = "active", limit: int | None = 100) -> dict[str, Any]:
+    """Alertmanager silences in Grafana's built-in Alertmanager:
+    ``[{id, state, matchers, starts_at, ends_at, created_by, comment}]``."""
+    if state not in SILENCE_STATES:
+        raise GrafanaError(f"state must be one of {', '.join(SILENCE_STATES)}")
+    items = [s for s in grafana_request("GET", "/api/alertmanager/grafana/api/v2/silences", config=config) or [] if isinstance(s, dict)]
+    if state != "any":
+        items = [s for s in items if (s.get("status") or {}).get("state") == state]
+    items.sort(key=lambda s: s.get("endsAt") or "", reverse=True)
+    rows = [
+        drop_empty(
+            {
+                "id": s.get("id"),
+                "state": (s.get("status") or {}).get("state"),
+                "matchers": _matchers(s.get("matchers") or []),
+                "starts_at": s.get("startsAt"),
+                "ends_at": s.get("endsAt"),
+                "created_by": s.get("createdBy"),
+                "comment": preview(s.get("comment"), 300)[0],
+            }
+        )
+        for s in items
+    ]
+    kept, cut = truncate(rows, limit)
+    return {"count": len(rows), "truncated": cut, "silences": kept}

runspec_grafana_core-0.1.0/runspec_grafana_core/annotations.py

@@ -0,0 +1,131 @@
+"""annotations.py — read and create annotations (``/api/annotations``).
+
+Annotations mark events on dashboards: deploys, incidents, alert state changes.
+Grafana stores times as epoch milliseconds; these helpers take the same time
+forms as the query verbs and return RFC 3339.
+"""
+
+from __future__ import annotations
+
+import time as _time
+from typing import Any
+
+from runspec_grafana_core.client import GrafanaConfig, GrafanaError, drop_empty, grafana_request, iso, parse_time, preview, truncate, window
+
+ANNOTATION_TYPES = ("annotation", "alert")
+
+
+def _ms(ts: float | None) -> int | None:
+    return None if ts is None else int(ts * 1000)
+
+
+def get_annotations(
+    config: GrafanaConfig,
+    start: str | None = None,
+    end: str | None = None,
+    dashboard_uid: str | None = None,
+    panel_id: int | None = None,
+    tags: list[str] | None = None,
+    match_any: bool = False,
+    type: str | None = None,
+    limit: int | None = 100,
+) -> dict[str, Any]:
+    """Annotations in ``start``..``end`` (default the last 24 hours), newest first.
+
+    ``tags`` must all match unless ``match_any``; ``type`` is ``annotation``
+    (user-made) or ``alert`` (alert state changes). Text is cut to 300 chars
+    (``text_chars`` gives the full length).
+    """
+    if type and type not in ANNOTATION_TYPES:
+        raise GrafanaError(f"type must be one of {', '.join(ANNOTATION_TYPES)}")
+    start_ts, end_ts = window(start, end, default_lookback=86400.0)
+    params = {
+        "from": _ms(start_ts),
+        "to": _ms(end_ts),
+        "dashboardUID": dashboard_uid,
+        "panelId": panel_id,
+        "tags": list(tags or []),
+        "matchAny": True if match_any else None,
+        "type": type,
+        "limit": limit + 1 if limit and limit > 0 else 5000,
+    }
+    items = [a for a in grafana_request("GET", "/api/annotations", config=config, params=params) or [] if isinstance(a, dict)]
+    kept, cut = truncate(items, limit)
+    rows = []
+    for a in kept:
+        text, full = preview(a.get("text"), 300)
+        rows.append(
+            drop_empty(
+                {
+                    "id": a.get("id"),
+                    "time": iso(a["time"] / 1000) if a.get("time") else None,
+                    "time_end": iso(a["timeEnd"] / 1000) if a.get("timeEnd") and a.get("timeEnd") != a.get("time") else None,
+                    "text": text,
+                    "text_chars": full,
+                    "tags": a.get("tags"),
+                    "dashboard_uid": a.get("dashboardUID"),
+                    "panel_id": a.get("panelId") or None,
+                    "alert_name": a.get("alertName"),
+                    "new_state": a.get("newState"),
+                    "by": a.get("login") or a.get("email"),
+                }
+            )
+        )
+    return {"start": iso(start_ts), "end": iso(end_ts), "count": len(rows), "truncated": cut, "annotations": rows}
+
+
+def get_annotation_tags(config: GrafanaConfig, tag: str | None = None, limit: int | None = 100) -> dict[str, Any]:
+    """Annotation tags in use, with how many annotations carry each; ``tag`` filters by prefix."""
+    body = grafana_request("GET", "/api/annotations/tags", config=config, params={"tag": tag, "limit": limit if limit and limit > 0 else None}) or {}
+    tags = ((body.get("result") or {}) if isinstance(body, dict) else {}).get("tags") or []
+    rows = [{"tag": t.get("tag"), "count": t.get("count")} for t in tags if isinstance(t, dict)]
+    rows.sort(key=lambda r: r["count"] or 0, reverse=True)
+    return {"count": len(rows), "tags": rows}
+
+
+def create_annotation(
+    config: GrafanaConfig,
+    text: str,
+    tags: list[str] | None = None,
+    dashboard_uid: str | None = None,
+    panel_id: int | None = None,
+    at: str | None = None,
+    end: str | None = None,
+) -> dict[str, Any]:
+    """Create an annotation at ``at`` (default now), or a region up to ``end``.
+
+    Without ``dashboard_uid`` it is an organization-wide annotation, shown on
+    any dashboard with a tag-filtered annotation query. Returns ``{id, time, …}``.
+    """
+    if not text.strip():
+        raise GrafanaError("Annotation text is empty")
+    if panel_id is not None and not dashboard_uid:
+        raise GrafanaError("panel_id needs dashboard_uid")
+    now = _time.time()
+    at_ts = parse_time(at, now=now)
+    start_ts = at_ts if at_ts is not None else now
+    end_ts = parse_time(end, now=now)
+    if end_ts is not None and end_ts < start_ts:
+        raise GrafanaError(f"end ({iso(end_ts)}) is before the annotation time ({iso(start_ts)})")
+    body = drop_empty(
+        {
+            "text": text,
+            "tags": list(tags or []),
+            "dashboardUID": dashboard_uid,
+            "panelId": panel_id,
+            "time": _ms(start_ts),
+            "timeEnd": _ms(end_ts),
+        }
+    )
+    result = grafana_request("POST", "/api/annotations", config=config, json_body=body) or {}
+    return drop_empty(
+        {
+            "id": result.get("id") if isinstance(result, dict) else None,
+            "time": iso(start_ts),
+            "time_end": iso(end_ts),
+            "dashboard_uid": dashboard_uid,
+            "panel_id": panel_id,
+            "tags": list(tags or []),
+            "message": result.get("message") if isinstance(result, dict) else None,
+        }
+    )

runspec_grafana_core-0.1.0/runspec_grafana_core/api.py

@@ -0,0 +1,37 @@
+"""api.py — a read-only escape hatch: GET any Grafana HTTP API path.
+
+For the API surface the dedicated helpers don't cover (org settings, teams,
+library panels, plugin settings …). GET only — anything that changes state
+goes through a helper with its own autonomy.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_grafana_core.client import GrafanaConfig, GrafanaError, grafana_request
+
+
+def parse_params(pairs: list[str] | None) -> dict[str, Any]:
+    """``["key=value", "tag=a", "tag=b"]`` → ``{"key": "value", "tag": ["a", "b"]}``."""
+    out: dict[str, Any] = {}
+    for pair in pairs or []:
+        key, sep, value = pair.partition("=")
+        if not sep or not key.strip():
+            raise GrafanaError(f"Query parameter {pair!r} is not key=value")
+        key = key.strip()
+        if key in out:
+            out[key] = [*(out[key] if isinstance(out[key], list) else [out[key]]), value]
+        else:
+            out[key] = value
+    return out
+
+
+def api_get(config: GrafanaConfig, path: str, params: list[str] | None = None) -> Any:
+    """GET ``path`` (must start with ``/api/``) and return the decoded JSON as-is."""
+    path = path.strip()
+    if not path.startswith("/api/"):
+        raise GrafanaError(f"Path must start with /api/ (got {path!r})")
+    if ".." in path.split("?")[0].split("/"):
+        raise GrafanaError("Path may not contain '..'")
+    return grafana_request("GET", path, config=config, params=parse_params(params))