netgreener_sdk

Python SDK for NetGreener — the AI developer agent and runtime control layer for resource, cost, and environmental impact.

Integrate NetGreener into your own tools and pipelines: authenticate, manage projects, upload run evidence, and access reports that link code and releases to verified CPU/GPU, cost, energy, carbon, and water impact.

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

Full handbook (CLI + VS Code + SDK + CI): ../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):

pip install -e ./netgreener_sdk

Requires Python 3.10+ and requests.

Quick start

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)

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:

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):

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:

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