netgreener-sdk 0.1.0__tar.gz

netgreener_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: netgreener_sdk
+Version: 0.1.0
+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'

netgreener_sdk-0.1.0/README.md

@@ -0,0 +1,82 @@
+# 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},
+)
+```
+
+## 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.
+
+## 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/*
+```

netgreener_sdk-0.1.0/netgreener_sdk/__init__.py

@@ -0,0 +1,5 @@
+"""Thin NetGreener API client (Phase 2 SDK skeleton)."""
+
+from netgreener_sdk.client import APIError, NetGreenerClient
+
+__all__ = ["APIError", "NetGreenerClient"]

netgreener_sdk-0.1.0/netgreener_sdk/client.py

@@ -0,0 +1,520 @@
+"""
+Minimal HTTP client for NetGreener API v1.
+
+Mirrors the paths used by the CLI (`netgreener.api_client`) without importing the CLI.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, MutableMapping, Optional
+from urllib.parse import quote
+
+import requests
+
+
+class APIError(Exception):
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class _AuthPreservingSession(requests.Session):
+    """Preserve Authorization and method on redirects (e.g. http→https)."""
+
+    def rebuild_auth(self, prepared_request, response):
+        return
+
+    def rebuild_method(self, _prepared_request, _response):
+        return
+
+
+class NetGreenerClient:
+    """
+    :param base_url: API root including ``/api/v1`` (e.g. ``https://host/api/v1``).
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        base_url: str = "http://localhost:8000/api/v1",
+        org_id: Optional[int] = None,
+        environment: Optional[str] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self._token = token
+        self._org_id = org_id
+        self._environment = environment
+        self._session = _AuthPreservingSession()
+
+    def _headers(self) -> Mapping[str, str]:
+        h: MutableMapping[str, str] = {"Content-Type": "application/json"}
+        if self._token:
+            h["Authorization"] = f"Bearer {self._token}"
+        if self._org_id is not None:
+            h["X-Organization-ID"] = str(self._org_id)
+        if self._environment:
+            h["X-Environment"] = self._environment
+        return h
+
+    def _raise(self, resp: requests.Response) -> None:
+        if resp.ok:
+            return
+        try:
+            body = resp.json()
+            detail = body.get("detail", resp.text)
+        except Exception:
+            detail = resp.text
+        if not isinstance(detail, str):
+            detail = str(detail)
+        raise APIError(resp.status_code, detail)
+
+    def login(self, email: str, password: str) -> dict[str, Any]:
+        resp = self._session.post(
+            f"{self.base_url}/auth/login",
+            json={"email": email, "password": password},
+            timeout=30,
+        )
+        self._raise(resp)
+        data = resp.json()
+        self._token = data.get("access_token")
+        return data
+
+    def set_token(self, token: Optional[str]) -> None:
+        self._token = token
+
+    def set_org_context(self, org_id: Optional[int], environment: Optional[str] = None) -> None:
+        """
+        Set org-scoped request context used by API authz and billing routes.
+        """
+        self._org_id = org_id
+        self._environment = environment
+
+    def get_access_token(self) -> Optional[str]:
+        """Bearer token set by ``login`` or ``set_token``."""
+        return self._token
+
+    def get_org_context(self) -> dict[str, Optional[str]]:
+        return {
+            "org_id": self._org_id,
+            "environment": self._environment,
+        }
+
+    def create_service_token(
+        self,
+        org_id: int,
+        scopes: list[str],
+        *,
+        environment: str = "dev",
+        expires_in_hours: int = 24 * 30,
+    ) -> dict[str, Any]:
+        payload = {
+            "org_id": org_id,
+            "environment": environment,
+            "scopes": scopes,
+            "expires_in_hours": expires_in_hours,
+        }
+        resp = self._session.post(
+            f"{self.base_url}/auth/service-token",
+            headers=self._headers(),
+            json=payload,
+            timeout=30,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def get_me(self) -> dict[str, Any]:
+        """GET ``/auth/me``; current user profile (requires a valid token)."""
+        resp = self._session.get(
+            f"{self.base_url}/auth/me",
+            headers=self._headers(),
+            timeout=30,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def post_run_session(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST ``/runsessions``; same contract as CLI run upload."""
+        resp = self._session.post(
+            f"{self.base_url}/runsessions",
+            headers=self._headers(),
+            json=payload,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def get_run_session(self, run_id: int) -> dict[str, Any]:
+        """GET ``/runsessions/{run_id}``."""
+        resp = self._session.get(
+            f"{self.base_url}/runsessions/{run_id}",
+            headers=self._headers(),
+            timeout=30,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def get_run_sessions(
+        self,
+        *,
+        project_id: Optional[int] = None,
+    ) -> list[dict[str, Any]]:
+        """GET ``/runsessions`` with optional ``project_id`` query."""
+        params: dict[str, int] = {}
+        if project_id is not None:
+            params["project_id"] = project_id
+        resp = self._session.get(
+            f"{self.base_url}/runsessions",
+            headers=self._headers(),
+            params=params or None,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def post_surrogate_training(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST ``/surrogate-training/``."""
+        resp = self._session.post(
+            f"{self.base_url}/surrogate-training/",
+            headers=self._headers(),
+            json=payload,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    # --- Features API (`/api/v1/features`); see `docs/CODEANALYZER_TO_API_SURFACE.md` ---
+
+    def post_feature_collection_input(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST ``/features/inputs``; requires existing ``feature_name`` in ``featuredefinition``."""
+        resp = self._session.post(
+            f"{self.base_url}/features/inputs",
+            headers=self._headers(),
+            json=payload,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def get_feature_collection_inputs(
+        self,
+        *,
+        project_id: Optional[int] = None,
+        feature_name: Optional[str] = None,
+        entered_by_user_id: Optional[int] = None,
+    ) -> list[dict[str, Any]]:
+        """GET ``/features/inputs`` with optional query filters."""
+        params: dict[str, Any] = {}
+        if project_id is not None:
+            params["project_id"] = project_id
+        if feature_name is not None:
+            params["feature_name"] = feature_name
+        if entered_by_user_id is not None:
+            params["entered_by_user_id"] = entered_by_user_id
+        resp = self._session.get(
+            f"{self.base_url}/features/inputs",
+            headers=self._headers(),
+            params=params or None,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def get_feature_collection_input(self, input_id: int) -> dict[str, Any]:
+        """GET ``/features/inputs/{input_id}``."""
+        resp = self._session.get(
+            f"{self.base_url}/features/inputs/{input_id}",
+            headers=self._headers(),
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def update_feature_collection_input(
+        self, input_id: int, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        """PUT ``/features/inputs/{input_id}`` (developer/admin)."""
+        resp = self._session.put(
+            f"{self.base_url}/features/inputs/{input_id}",
+            headers=self._headers(),
+            json=payload,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def delete_feature_collection_input(self, input_id: int) -> dict[str, Any]:
+        """DELETE ``/features/inputs/{input_id}``."""
+        resp = self._session.delete(
+            f"{self.base_url}/features/inputs/{input_id}",
+            headers=self._headers(),
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def list_project_feature_collection_inputs(self, project_id: int) -> list[dict[str, Any]]:
+        """GET ``/features/project/{project_id}/inputs``."""
+        resp = self._session.get(
+            f"{self.base_url}/features/project/{project_id}/inputs",
+            headers=self._headers(),
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def list_feature_definitions(self) -> list[dict[str, Any]]:
+        """GET ``/features/definitions``."""
+        resp = self._session.get(
+            f"{self.base_url}/features/definitions",
+            headers=self._headers(),
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def post_feature_definition(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST ``/features/definitions``."""
+        resp = self._session.post(
+            f"{self.base_url}/features/definitions",
+            headers=self._headers(),
+            json=payload,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def get_feature_definition(self, feature_name: str) -> dict[str, Any]:
+        """GET ``/features/definitions/{feature_name}``."""
+        safe_name = quote(str(feature_name), safe="")
+        resp = self._session.get(
+            f"{self.base_url}/features/definitions/{safe_name}",
+            headers=self._headers(),
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def update_feature_definition(
+        self, feature_name: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        """PUT ``/features/definitions/{feature_name}``."""
+        safe_name = quote(str(feature_name), safe="")
+        resp = self._session.put(
+            f"{self.base_url}/features/definitions/{safe_name}",
+            headers=self._headers(),
+            json=payload,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def delete_feature_definition(self, feature_name: str) -> dict[str, Any]:
+        """DELETE ``/features/definitions/{feature_name}``."""
+        safe_name = quote(str(feature_name), safe="")
+        resp = self._session.delete(
+            f"{self.base_url}/features/definitions/{safe_name}",
+            headers=self._headers(),
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    # --- Project feature metadata (Parquet / on-disk path) ---
+
+    def get_project_feature_metadata(self, project_id: int) -> dict[str, Any]:
+        """GET ``/features/project/{project_id}/feature-metadata``."""
+        resp = self._session.get(
+            f"{self.base_url}/features/project/{project_id}/feature-metadata",
+            headers=self._headers(),
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def post_project_feature_metadata(
+        self, project_id: int, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        """POST ``/features/project/{project_id}/feature-metadata`` (body includes ``project_id`` matching path)."""
+        body = {**payload, "project_id": project_id}
+        resp = self._session.post(
+            f"{self.base_url}/features/project/{project_id}/feature-metadata",
+            headers=self._headers(),
+            json=body,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def put_project_feature_metadata(
+        self, project_id: int, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        """PUT ``/features/project/{project_id}/feature-metadata``."""
+        resp = self._session.put(
+            f"{self.base_url}/features/project/{project_id}/feature-metadata",
+            headers=self._headers(),
+            json=payload,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def delete_project_feature_metadata(self, project_id: int) -> dict[str, Any]:
+        """DELETE ``/features/project/{project_id}/feature-metadata``."""
+        resp = self._session.delete(
+            f"{self.base_url}/features/project/{project_id}/feature-metadata",
+            headers=self._headers(),
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    # --- Projects ---
+
+    def get_projects(self, *, is_active: Optional[bool] = None) -> list[dict[str, Any]]:
+        """GET ``/projects`` with optional ``is_active`` filter."""
+        params: dict[str, Any] = {}
+        if is_active is not None:
+            params["is_active"] = is_active
+        resp = self._session.get(
+            f"{self.base_url}/projects",
+            headers=self._headers(),
+            params=params or None,
+            timeout=30,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    # --- Credit quote ---
+
+    def quote_credits(self, org_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST ``/billing/organizations/{org_id}/credit-quote``."""
+        resp = self._session.post(
+            f"{self.base_url}/billing/organizations/{org_id}/credit-quote",
+            headers=self._headers(),
+            json=payload,
+            timeout=30,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    # --- KPI estimation (Phase 7) ---
+
+    def get_project_estimate_feature_status(self, project_id: int) -> dict[str, Any]:
+        """GET ``/runs/projects/{project_id}/estimate-feature-status``."""
+        resp = self._session.get(
+            f"{self.base_url}/runs/projects/{project_id}/estimate-feature-status",
+            headers=self._headers(),
+            timeout=30,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def estimate_run(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST ``/runs/estimate``; general estimation from explicit feature_values."""
+        resp = self._session.post(
+            f"{self.base_url}/runs/estimate",
+            headers=self._headers(),
+            json=payload,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def estimate_project(self, project_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST ``/runs/projects/{project_id}/estimate``; feature values resolved server-side."""
+        resp = self._session.post(
+            f"{self.base_url}/runs/projects/{project_id}/estimate",
+            headers=self._headers(),
+            json=payload,
+            timeout=60,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def get_run_estimate(self, run_id: int) -> dict[str, Any]:
+        """GET ``/runs/{run_id}/estimate``; fetch persisted estimate for a completed run."""
+        resp = self._session.get(
+            f"{self.base_url}/runs/{run_id}/estimate",
+            headers=self._headers(),
+            timeout=30,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    # --- Analyze / findings (CLI parity) ---
+
+    def analyze_project_files(
+        self, project_id: int, per_file: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """POST ``/analyze/project``; return findings (persist with ``post_findings_batch``)."""
+        files_payload = [
+            {"path": entry["rel_path"], "features": entry["features"]}
+            for entry in per_file
+            if isinstance(entry, dict) and "rel_path" in entry and "features" in entry
+        ]
+        if not files_payload:
+            return []
+        resp = self._session.post(
+            f"{self.base_url}/analyze/project",
+            headers=self._headers(),
+            json={"project_id": project_id, "files": files_payload},
+            timeout=60,
+        )
+        self._raise(resp)
+        data = resp.json()
+        findings = data.get("findings", [])
+        return findings if isinstance(findings, list) else []
+
+    def post_findings_batch(self, findings: list[dict[str, Any]]) -> dict[str, Any]:
+        """POST ``/findings/batch``."""
+        resp = self._session.post(
+            f"{self.base_url}/findings/batch",
+            headers=self._headers(),
+            json={"findings": findings},
+            timeout=30,
+        )
+        self._raise(resp)
+        return resp.json()
+
+    def get_project_findings(self, project_id: int) -> list[dict[str, Any]]:
+        resp = self._session.get(
+            f"{self.base_url}/findings/project/{project_id}",
+            headers=self._headers(),
+            timeout=30,
+        )
+        self._raise(resp)
+        data = resp.json()
+        return data if isinstance(data, list) else []
+
+    def get_surrogate_training_for_project(self, project_id: int) -> list[dict[str, Any]]:
+        resp = self._session.get(
+            f"{self.base_url}/surrogate-training/project/{project_id}",
+            headers=self._headers(),
+            timeout=30,
+        )
+        self._raise(resp)
+        data = resp.json()
+        return data if isinstance(data, list) else []
+
+    def submit_finding_feedback(
+        self,
+        finding_id: int,
+        *,
+        verdict: str,
+        note: str | None = None,
+        severity: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"verdict": verdict}
+        if note:
+            payload["note"] = note
+        if severity:
+            payload["severity"] = severity
+        resp = self._session.post(
+            f"{self.base_url}/findings/{finding_id}/feedback",
+            headers=self._headers(),
+            json=payload,
+            timeout=15,
+        )
+        self._raise(resp)
+        return resp.json()

netgreener_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "netgreener_sdk"
+version = "0.1.0"
+description = "Thin Python client for the NetGreener HTTP API (auth, run sessions, surrogate training)."
+authors = [{ name = "Saeed Khazaee", email = "saeed@netgreener.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.28.0,<3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[build-system]
+requires = ["hatchling>=1.21.0"]
+build-backend = "hatchling.build"

netgreener_sdk-0.1.0/tests/conftest.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+# Ensure imports resolve when tests are run from monorepo root:
+# `python -m pytest netgreener_sdk/tests -q`
+repo_pkg_root = Path(__file__).resolve().parents[1]
+if str(repo_pkg_root) not in sys.path:
+    sys.path.insert(0, str(repo_pkg_root))

netgreener_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,332 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from netgreener_sdk.client import APIError, NetGreenerClient
+
+
+class DummyResponse:
+    def __init__(self, status_code: int, payload: Any = None, text: str = "") -> None:
+        self.status_code = status_code
+        self._payload = payload
+        self.text = text
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status_code < 300
+
+    def json(self):
+        if isinstance(self._payload, Exception):
+            raise self._payload
+        return self._payload
+
+
+class DummySession:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, str, dict[str, Any]]] = []
+        self.responses: list[DummyResponse] = []
+
+    def enqueue(self, response: DummyResponse) -> None:
+        self.responses.append(response)
+
+    def _pop(self, method: str, url: str, **kwargs):
+        self.calls.append((method, url, kwargs))
+        assert self.responses, "No queued response for request"
+        return self.responses.pop(0)
+
+    def get(self, url, **kwargs):
+        return self._pop("GET", url, **kwargs)
+
+    def post(self, url, **kwargs):
+        return self._pop("POST", url, **kwargs)
+
+    def put(self, url, **kwargs):
+        return self._pop("PUT", url, **kwargs)
+
+    def delete(self, url, **kwargs):
+        return self._pop("DELETE", url, **kwargs)
+
+
+def _client_and_session() -> tuple[NetGreenerClient, DummySession]:
+    client = NetGreenerClient(base_url="http://localhost:8000/api/v1")
+    session = DummySession()
+    client._session = session  # type: ignore[attr-defined]
+    return client, session
+
+
+def test_login_sets_token():
+    client, session = _client_and_session()
+    session.enqueue(
+        DummyResponse(
+            200,
+            {"access_token": "abc", "user": {"user_id": 1}, "token_type": "bearer"},
+        )
+    )
+
+    data = client.login("a@b.com", "pw")
+
+    assert data["access_token"] == "abc"
+    assert client.get_access_token() == "abc"
+    method, url, kwargs = session.calls[0]
+    assert method == "POST"
+    assert url.endswith("/auth/login")
+    assert kwargs["json"]["email"] == "a@b.com"
+
+
+def test_get_me_uses_auth_header():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, {"user_id": 7, "email": "x@y.com"}))
+
+    payload = client.get_me()
+
+    assert payload["user_id"] == 7
+    method, url, kwargs = session.calls[0]
+    assert method == "GET"
+    assert url.endswith("/auth/me")
+    assert kwargs["headers"]["Authorization"] == "Bearer tok"
+
+
+def test_quote_credits_uses_billing_quote_path():
+    client, session = _client_and_session()
+    session.enqueue(DummyResponse(200, {"action": "run_estimate", "total_credits": 12}))
+
+    data = client.quote_credits(3, {"action": "run_estimate", "reported_input_tokens": 1000})
+
+    assert data["total_credits"] == 12
+    method, url, kwargs = session.calls[0]
+    assert method == "POST"
+    assert url.endswith("/billing/organizations/3/credit-quote")
+    assert kwargs["json"]["action"] == "run_estimate"
+
+
+def test_feature_definitions_crud_paths_and_encoding():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, [{"feature_name": "f1"}]))  # list
+    session.enqueue(DummyResponse(200, {"feature_name": "f/a"}))  # create
+    session.enqueue(DummyResponse(200, {"feature_name": "f/a"}))  # get
+    session.enqueue(DummyResponse(200, {"feature_name": "f/a"}))  # update
+    session.enqueue(DummyResponse(200, {"success": True}))  # delete
+
+    client.list_feature_definitions()
+    client.post_feature_definition({"feature_name": "f/a"})
+    client.get_feature_definition("f/a")
+    client.update_feature_definition("f/a", {"description": "x"})
+    client.delete_feature_definition("f/a")
+
+    assert session.calls[0][1].endswith("/features/definitions")
+    assert session.calls[1][1].endswith("/features/definitions")
+    assert session.calls[2][1].endswith("/features/definitions/f%2Fa")
+    assert session.calls[3][1].endswith("/features/definitions/f%2Fa")
+    assert session.calls[4][1].endswith("/features/definitions/f%2Fa")
+
+
+def test_project_feature_metadata_post_injects_project_id():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, {"project_id": 2}))
+
+    client.post_project_feature_metadata(2, {"parquet_path": "/tmp/f.parquet"})
+
+    method, url, kwargs = session.calls[0]
+    assert method == "POST"
+    assert url.endswith("/features/project/2/feature-metadata")
+    assert kwargs["json"]["project_id"] == 2
+    assert kwargs["json"]["parquet_path"] == "/tmp/f.parquet"
+
+
+def test_api_error_uses_detail_from_json():
+    client, session = _client_and_session()
+    session.enqueue(DummyResponse(404, {"detail": "Feature not found"}))
+
+    with pytest.raises(APIError) as exc:
+        client.get_feature_definition("missing")
+    assert exc.value.status_code == 404
+    assert "Feature not found" in exc.value.detail
+
+
+def test_api_error_falls_back_to_text_when_json_unavailable():
+    client, session = _client_and_session()
+    session.enqueue(DummyResponse(500, payload=ValueError("bad json"), text="server exploded"))
+
+    with pytest.raises(APIError) as exc:
+        client.get_feature_definition("anything")
+    assert exc.value.status_code == 500
+    assert "server exploded" in exc.value.detail
+
+
+# ---------------------------------------------------------------------------
+# Run sessions
+# ---------------------------------------------------------------------------
+
+
+def test_get_run_session_uses_correct_path_and_token():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, {"run_id": 42, "project_id": 1}))
+
+    data = client.get_run_session(42)
+
+    assert data["run_id"] == 42
+    method, url, kwargs = session.calls[0]
+    assert method == "GET"
+    assert url.endswith("/runsessions/42")
+    assert kwargs["headers"]["Authorization"] == "Bearer tok"
+
+
+def test_get_run_sessions_no_filter():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, [{"run_id": 1}, {"run_id": 2}]))
+
+    data = client.get_run_sessions()
+
+    assert len(data) == 2
+    method, url, kwargs = session.calls[0]
+    assert method == "GET"
+    assert url.endswith("/runsessions")
+    assert kwargs.get("params") is None
+
+
+def test_get_run_sessions_project_filter():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, [{"run_id": 5}]))
+
+    client.get_run_sessions(project_id=7)
+
+    _, _, kwargs = session.calls[0]
+    assert kwargs["params"]["project_id"] == 7
+
+
+def test_post_run_session_sends_payload():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    payload = {"project_id": 3, "start_time": "2026-01-01T00:00:00Z", "end_time": "2026-01-01T01:00:00Z"}
+    session.enqueue(DummyResponse(200, {"run_id": 99}))
+
+    data = client.post_run_session(payload)
+
+    assert data["run_id"] == 99
+    method, url, kwargs = session.calls[0]
+    assert method == "POST"
+    assert url.endswith("/runsessions")
+    assert kwargs["json"]["project_id"] == 3
+
+
+# ---------------------------------------------------------------------------
+# Projects
+# ---------------------------------------------------------------------------
+
+
+def test_get_projects_no_filter():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, [{"project_id": 1, "name": "P1"}, {"project_id": 2, "name": "P2"}]))
+
+    data = client.get_projects()
+
+    assert len(data) == 2
+    method, url, kwargs = session.calls[0]
+    assert method == "GET"
+    assert url.endswith("/projects")
+    assert kwargs.get("params") is None
+
+
+def test_get_projects_active_filter():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, [{"project_id": 1}]))
+
+    client.get_projects(is_active=True)
+
+    _, _, kwargs = session.calls[0]
+    assert kwargs["params"]["is_active"] is True
+
+
+# ---------------------------------------------------------------------------
+# KPI estimation (Phase 7)
+# ---------------------------------------------------------------------------
+
+
+def test_get_project_estimate_feature_status():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, {"project_id": 3, "feature_count": 12, "feature_source": "surrogate_training_data", "feature_keys": ["k1", "k2"]}))
+
+    data = client.get_project_estimate_feature_status(3)
+
+    assert data["feature_count"] == 12
+    method, url, kwargs = session.calls[0]
+    assert method == "GET"
+    assert url.endswith("/runs/projects/3/estimate-feature-status")
+    assert kwargs["headers"]["Authorization"] == "Bearer tok"
+
+
+def test_estimate_run_posts_feature_values():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    payload = {"feature_values": {"num_layers": 4}, "use_llm": False}
+    session.enqueue(DummyResponse(200, {"estimates": {"energy_kwh": {"low": 0.1, "high": 0.5}}, "confidence": "low", "estimate_mode": "stub"}))
+
+    data = client.estimate_run(payload)
+
+    assert "estimates" in data
+    method, url, kwargs = session.calls[0]
+    assert method == "POST"
+    assert url.endswith("/runs/estimate")
+    assert kwargs["json"]["use_llm"] is False
+
+
+def test_estimate_project_uses_project_path():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, {"estimates": {}, "confidence": "medium", "estimate_mode": "llm", "model": "gpt-4o"}))
+
+    data = client.estimate_project(5, {"use_llm": True, "feature_values": {}})
+
+    assert data["confidence"] == "medium"
+    method, url, kwargs = session.calls[0]
+    assert method == "POST"
+    assert url.endswith("/runs/projects/5/estimate")
+    assert kwargs["json"]["use_llm"] is True
+
+
+def test_get_run_estimate_uses_correct_path():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(200, {"run_id": 7, "project_id": 2, "run_estimate_v0": {"confidence": "high"}}))
+
+    data = client.get_run_estimate(7)
+
+    assert data["run_id"] == 7
+    method, url, _ = session.calls[0]
+    assert method == "GET"
+    assert url.endswith("/runs/7/estimate")
+
+
+def test_estimate_project_raises_on_422():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    session.enqueue(DummyResponse(422, {"detail": "No extracted feature values found"}))
+
+    with pytest.raises(APIError) as exc:
+        client.estimate_project(9, {"feature_values": {}, "use_llm": True})
+    assert exc.value.status_code == 422
+    assert "No extracted feature values found" in exc.value.detail
+
+
+def test_org_context_headers_forwarded():
+    client, session = _client_and_session()
+    client.set_token("tok")
+    client.set_org_context(org_id=42, environment="prod")
+    session.enqueue(DummyResponse(200, {}))
+
+    client.get_projects()
+
+    _, _, kwargs = session.calls[0]
+    assert kwargs["headers"]["X-Organization-ID"] == "42"
+    assert kwargs["headers"]["X-Environment"] == "prod"