Metadata-Version: 2.4
Name: kubegraf
Version: 0.1.0
Summary: Official Python client for the KubeGraf API
Project-URL: Homepage, https://kubegraf.io
Project-URL: Documentation, https://kubegraf.io/docs/api
Project-URL: Source, https://github.com/kubegraf/kubegraf-api
Author-email: KubeGraf <hello@kubegraf.io>
License-Expression: Apache-2.0
Keywords: aiops,kubegraf,kubernetes,observability,sre
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# kubegraf — Python client for the KubeGraf API

Official, zero-dependency Python client for the [KubeGraf](https://kubegraf.io)
API. Read your workspace's incidents and Agent Fleet, and run metered AI
investigations.

KubeGraf is a paid subscription product. Authenticate with a workspace-scoped
subscription API key (`kgkey_…`); usage counts against your plan and AI paths
run on KubeGraf-managed infrastructure — never BYOK.

## Install

```sh
pip install kubegraf
```

Requires Python ≥ 3.8. No runtime dependencies (stdlib `urllib` only).

## Usage

```python
import os
from kubegraf import KubeGraf, KubeGrafError

kg = KubeGraf(api_key=os.environ["KUBEGRAF_API_KEY"])

# Incidents (status: open | acknowledged | resolved | false_positive)
for inc in kg.incidents.list(status="open", limit=20)["incidents"]:
    print(inc["id"], inc["severity"], inc["title"])

# Agent Fleet
for c in kg.clusters.list()["clusters"]:
    print(c["name"], c["status"], f'{c["nodes"]} nodes / {c["pods"]} pods')

# AI investigation (metered; requires a key with the `write` scope)
try:
    result = kg.investigations.start(incident_id="inc_123", mode="deep")
    print(result["analysis"]["root_cause"])
except KubeGrafError as e:
    print("failed:", e.status, e.code, str(e))
```

### Self-hosted

Point `base_url` at your install's host:

```python
kg = KubeGraf(api_key="kgkey_…", base_url="https://kubegraf.your-company.com")
```

## Errors

Every non-2xx response raises `KubeGrafError` with `.status` (HTTP code, `0`
for network/timeout), `.code` (machine-readable), and `.detail` (parsed body).
`402` = plan quota exhausted / subscription inactive; `429` = rate limited.
