Metadata-Version: 2.5
Name: kubegraf
Version: 0.2.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.

Authenticate with a workspace-scoped 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.

## Existing async investigation tasks

```python
workspace_id = "11111111-1111-1111-1111-111111111111"
started = kg.tasks.start(workspace_id, "Investigate checkout errors",
                         message_id="persisted-request-uuid")
if "task" in started:
    current = kg.tasks.get(workspace_id, started["task"]["id"], history_length=1)
    print(current["status"]["state"])  # not proof of verified recovery
page = kg.tasks.list(workspace_id, page_size=20)
# Pass a nonempty page["nextPageToken"] on a later explicit list call.
```

The existing A2A1.0 gateway requires `missions:read` for reads and `missions:write` plus the server's live creator-role checks for start/cancel. Reuse a persisted `message_id` with the same key when manually retrying an uncertain start; no automatic retry or polling occurs. `kg.tasks.cancel(workspace_id, task_id)` requests investigation cancellation, not rollback. HTTP200 RPC errors raise `KubeGrafRpcError`, whose `rpc_code`, `status` and `detail` preserve the structured refusal. Ordinary HTTP/network errors remain `KubeGrafError`. See [shared scope, idempotency and limitations](../README.md#durable-async-task-clients), including bounded message IDs, history projection and separate package-publication gate.
