Metadata-Version: 2.4
Name: netgreener_sdk
Version: 0.1.1
Summary: Thin Python client for the NetGreener HTTP API (auth, run sessions, surrogate training).
Author-email: Saeed Khazaee <saeed@netgreener.com>
Requires-Python: >=3.10
Requires-Dist: requests<3,>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# netgreener_sdk

Thin Python client for the NetGreener HTTP API (`/api/v1`).

> **Full handbook (CLI + VS Code + SDK + CI):** [`../docs/PROGRAMMER_BOOKLET.md`](../docs/PROGRAMMER_BOOKLET.md) Same contracts as `api_server` routers; paths mirror `netgreener_cli/netgreener/api_client.py` with extra **`/features`** coverage.

## Install

From the repo (editable):

```bash
pip install -e ./netgreener_sdk
```

Requires Python **3.10+** and `requests`.

## Quick start

```python
from netgreener_sdk import NetGreenerClient, APIError

client = NetGreenerClient(base_url="http://localhost:8000/api/v1")
client.login(email="you@example.com", password="…")
me = client.get_me()
print(me["email"])

# Project feature metadata (Parquet / path pointer)
row = client.post_project_feature_metadata(
    1,
    {"parquet_path": "/data/features.parquet", "feature_version": 1},
)

# Repo-aware project (git_url match order mirrors CLI)
project = client.get_or_create_project(
    "My ML repo",
    "/work/my-ml",
    git_url="https://github.com/acme/my-ml.git",
)

# Report AI summary credit quote (Phase 8d)
quote = client.quote_report_ai_summary(
    org_id=1,
    payload={
        "template": "sustainability",
        "scope_type": "org",
        "period_config": {
            "primary": {"from": "2026-04-01", "to": "2026-04-30"},
            "comparisons": [],
        },
    },
)
print(quote["total_credits"])

# Generate and download (Phase 8 SDK P2)
result = client.generate_report(
    1,
    {
        "template": "sustainability",
        "scope_type": "org",
        "period_config": {
            "primary": {"from": "2026-04-01", "to": "2026-04-30"},
            "comparisons": [],
        },
        "output_format": "both",
    },
)
report_id = result["report"]["report_id"]
pdf_bytes = client.download_report(1, report_id, format="pdf")
```

## Base URL

Pass the API root **including** `/api/v1`, e.g. `https://your-host/api/v1`.

## Auth

- **`login(email, password)`**; sets the bearer token on the client; response includes `user`, `access_token`, `expires_in`.
- **`set_token(token)`**; use an existing JWT.
- **`get_access_token()`**; current token or `None`.
- **`get_me()`**; `GET /auth/me` (requires valid token).

Feature metadata **writes** on the server require **developer** or **admin**; **GET** requires project access.

### Projects & reports (Phase 3b)

| Method | HTTP |
|--------|------|
| `get_projects` | `GET /projects` |
| `create_project` | `POST /projects` |
| `update_project` | `PUT /projects/{id}` |
| `get_or_create_project` | list + match by `git_url` → directory → name; create or sync |
| `quote_report_ai_summary` | `POST /organizations/{org_id}/reports/ai-summary/quote` |
| `preview_report` / `generate_report` | `POST .../reports/preview` / `.../generate` |
| `get_report_history` / `download_report` | `GET .../history` / `.../{report_id}/download` |
| `get_report_settings` / `update_report_settings` | schedule + cost assumptions |
| `run_scheduled_report_now` | `POST .../reports/schedule/run-now` |

Local analyze (`--paths`, `analyze_local`) stays in the **`netgreener`** CLI package, not the SDK.

## See also

- `docs/CODEANALYZER_TO_API_SURFACE.md`; which endpoints exist and how they map to CodeAnalyzer outputs.
- `docs/PLAN_INDEX.md`; full product/engineering plan checklist.

## Tests

From repo root:

```bash
python -m pytest netgreener_sdk/tests -q
```

## Publish (CI)

**Same PyPI token as the CLI** — Azure Library group `Package_credential`, secret `PYPI_API_TOKEN`, must allow upload to both `netgreener` and `netgreener_sdk`.

**Different pipeline and tag** (not the CLI pipeline):

| Package | Pipeline | Git tag | PyPI name |
|---------|----------|---------|-----------|
| CLI | `azure-pipelines-cli-publish.yml` | `cli-v*.*.*` | `netgreener` |
| SDK | `azure-pipelines-sdk-publish.yml` | `sdk-v*.*.*` | `netgreener_sdk` |

Example SDK release: `git tag sdk-v0.1.0 && git push origin sdk-v0.1.0`

## Pre-publish local build (recommended)

Before pushing the `sdk-v...` tag, verify the wheel/sdist build is clean:

```bash
python -m pip install --upgrade pip
python -m pip install build twine
python -m build netgreener_sdk
python -m twine check netgreener_sdk/dist/*
```
