nessyapi-sdk 0.2.0__tar.gz

nessyapi_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: nessyapi-sdk
+Version: 0.2.0
+Summary: Python SDK for NessyAPI — Clinical Decision Support API
+Author-email: "HealthyNess.cz" <dev@healthyness.cz>
+License: MIT
+Project-URL: Homepage, https://healthyness.cz
+Project-URL: Documentation, https://github.com/jachymvrtiskaHN/NessyAPI/tree/master/sdk
+Project-URL: Repository, https://github.com/jachymvrtiskaHN/NessyAPI
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# NessyAPI Python SDK
+
+Python SDK for [NessyAPI](https://healthyness.cz) — Clinical Decision Support API.
+
+## Install
+
+```bash
+pip install nessyapi-sdk
+```
+
+## Quick Start
+
+```python
+from nessyapi_sdk import NessyClient
+
+with NessyClient(api_key="nsy_live_...") as client:
+    # Run a full assessment
+    results = client.run_assessment("headache", age=35, sex="male")
+    
+    print(f"Triage: {results.triage_level}")
+    for dx in results.differentials:
+        print(f"  {dx.diagnosis}: {dx.probability:.0%}")
+```
+
+## Async
+
+```python
+from nessyapi_sdk import AsyncNessyClient
+
+async with AsyncNessyClient(api_key="nsy_live_...") as client:
+    session = await client.create_session("chest_pain", age=55, sex="male")
+    result = await client.answer(session.session_id, "q1", raw_text="pressure pain")
+    final = await client.finalize(session.session_id)
+```
+
+## Features
+
+- Sync and async clients
+- Typed response models (dataclasses)
+- Automatic retry with exponential backoff (429, 5xx)
+- Patient profile management
+- Webhook signature verification
+
+## Links
+
+- [API Reference](https://github.com/jachymvrtiskaHN/NessyAPI/blob/master/docs/api-reference.md)
+- [SDK Guide](https://github.com/jachymvrtiskaHN/NessyAPI/blob/master/docs/sdk-guide.md)

nessyapi_sdk-0.2.0/README.md

@@ -0,0 +1,47 @@
+# NessyAPI Python SDK
+
+Python SDK for [NessyAPI](https://healthyness.cz) — Clinical Decision Support API.
+
+## Install
+
+```bash
+pip install nessyapi-sdk
+```
+
+## Quick Start
+
+```python
+from nessyapi_sdk import NessyClient
+
+with NessyClient(api_key="nsy_live_...") as client:
+    # Run a full assessment
+    results = client.run_assessment("headache", age=35, sex="male")
+    
+    print(f"Triage: {results.triage_level}")
+    for dx in results.differentials:
+        print(f"  {dx.diagnosis}: {dx.probability:.0%}")
+```
+
+## Async
+
+```python
+from nessyapi_sdk import AsyncNessyClient
+
+async with AsyncNessyClient(api_key="nsy_live_...") as client:
+    session = await client.create_session("chest_pain", age=55, sex="male")
+    result = await client.answer(session.session_id, "q1", raw_text="pressure pain")
+    final = await client.finalize(session.session_id)
+```
+
+## Features
+
+- Sync and async clients
+- Typed response models (dataclasses)
+- Automatic retry with exponential backoff (429, 5xx)
+- Patient profile management
+- Webhook signature verification
+
+## Links
+
+- [API Reference](https://github.com/jachymvrtiskaHN/NessyAPI/blob/master/docs/api-reference.md)
+- [SDK Guide](https://github.com/jachymvrtiskaHN/NessyAPI/blob/master/docs/sdk-guide.md)

nessyapi_sdk-0.2.0/nessyapi_sdk/__init__.py

@@ -0,0 +1,32 @@
+"""NessyAPI Python SDK."""
+
+from nessyapi_sdk.async_client import AsyncNessyClient
+from nessyapi_sdk.client import NessyAPIError, NessyClient
+from nessyapi_sdk.models import (
+    AnswerResponse,
+    BalanceResponse,
+    Differential,
+    PatientProfile,
+    Question,
+    ResultsResponse,
+    SessionResponse,
+    UsageResponse,
+)
+from nessyapi_sdk.webhook import verify_webhook_signature
+
+__all__ = [
+    "NessyClient",
+    "AsyncNessyClient",
+    "NessyAPIError",
+    "verify_webhook_signature",
+    # Response models
+    "SessionResponse",
+    "AnswerResponse",
+    "ResultsResponse",
+    "BalanceResponse",
+    "UsageResponse",
+    "PatientProfile",
+    "Question",
+    "Differential",
+]
+__version__ = "0.2.0"

nessyapi_sdk-0.2.0/nessyapi_sdk/async_client.py

@@ -0,0 +1,258 @@
+"""
+NessyAPI Python SDK — async client.
+
+Usage:
+    from nessyapi_sdk import AsyncNessyClient
+
+    async with AsyncNessyClient(api_key="nsy_live_...") as client:
+        session = await client.create_session("headache", age=35, sex="male")
+        result = await client.answer(session.session_id, "q1", raw_text="3 days")
+        final = await client.finalize(session.session_id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from nessyapi_sdk.client import DEFAULT_BASE_URL, NessyAPIError, _MAX_RETRIES, _RETRYABLE_STATUSES
+from nessyapi_sdk.models import (
+    AnswerResponse,
+    BalanceResponse,
+    PatientProfile,
+    ResultsResponse,
+    SessionResponse,
+    UsageResponse,
+)
+
+
+class AsyncNessyClient:
+    """Async NessyAPI client with retry and typed responses."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = _MAX_RETRIES,
+    ):
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    async def _request(self, method: str, path: str, **kwargs) -> dict[str, Any]:
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = await self._client.request(method, path, **kwargs)
+            except httpx.TransportError as e:
+                last_exc = e
+                if attempt < self._max_retries:
+                    await asyncio.sleep(2 ** attempt)
+                    continue
+                raise
+
+            if resp.status_code < 400:
+                return resp.json()
+
+            if resp.status_code in _RETRYABLE_STATUSES and attempt < self._max_retries:
+                retry_after = resp.headers.get("Retry-After")
+                wait = float(retry_after) if retry_after else 2 ** attempt
+                await asyncio.sleep(min(wait, 60))
+                continue
+
+            try:
+                body = resp.json()
+            except Exception:
+                body = {"error": resp.text}
+            raise NessyAPIError(resp.status_code, body)
+
+        raise last_exc or NessyAPIError(500, {"error": "Max retries exceeded"})
+
+    # --- Session Lifecycle ---
+
+    async def create_session(
+        self,
+        chief_complaint: str,
+        age: int | None = None,
+        sex: str | None = None,
+        free_text: str | None = None,
+    ) -> SessionResponse:
+        """Create a new clinical session. Cost: 1 token."""
+        payload: dict[str, Any] = {"chief_complaint": chief_complaint}
+        if age is not None:
+            payload["age"] = age
+        if sex is not None:
+            payload["sex"] = sex
+        if free_text is not None:
+            payload["free_text"] = free_text
+        return SessionResponse.from_dict(await self._request("POST", "/v1/sessions", json=payload))
+
+    async def route(self, session_id: str, text: str) -> AnswerResponse:
+        """Route free-text to clinical branch. Cost: 5 tokens."""
+        data = await self._request("POST", f"/v1/sessions/{session_id}/route", json={"text": text})
+        return AnswerResponse.from_dict(data)
+
+    async def answer(
+        self,
+        session_id: str,
+        question_id: str,
+        *,
+        raw_text: str | None = None,
+        extracted_fields: dict[str, Any] | None = None,
+        extracted_flags: list[str] | None = None,
+        skip: bool = False,
+    ) -> AnswerResponse:
+        """Submit a patient answer. Cost: 8 tokens (0 if skip)."""
+        payload: dict[str, Any] = {"question_id": question_id}
+        if raw_text is not None:
+            payload["raw_text"] = raw_text
+        if extracted_fields:
+            payload["extracted_fields"] = extracted_fields
+        if extracted_flags:
+            payload["extracted_flags"] = extracted_flags
+        if skip:
+            payload["skip"] = True
+        return AnswerResponse.from_dict(
+            await self._request("POST", f"/v1/sessions/{session_id}/answer", json=payload)
+        )
+
+    async def get_results(self, session_id: str) -> ResultsResponse:
+        """Get current differentials and triage. FREE."""
+        return ResultsResponse.from_dict(
+            await self._request("GET", f"/v1/sessions/{session_id}/results")
+        )
+
+    async def get_state(self, session_id: str) -> dict[str, Any]:
+        """Get session state. FREE."""
+        return await self._request("GET", f"/v1/sessions/{session_id}/state")
+
+    async def finalize(self, session_id: str) -> ResultsResponse:
+        """Finalize session and get full results. FREE."""
+        return ResultsResponse.from_dict(
+            await self._request("POST", f"/v1/sessions/{session_id}/finalize")
+        )
+
+    # --- Patient Profiles ---
+
+    async def get_patient(self, patient_id: str) -> PatientProfile:
+        """Get patient profile."""
+        return PatientProfile.from_dict(
+            await self._request("GET", f"/v1/patients/{patient_id}/profile")
+        )
+
+    async def update_patient(
+        self,
+        patient_id: str,
+        *,
+        chronic_conditions: list[str] | None = None,
+        current_medications: list[str] | None = None,
+        allergies: list[str] | None = None,
+        risk_factors: list[str] | None = None,
+        family_history: list[str] | None = None,
+        smoking_status: str | None = None,
+        alcohol_status: str | None = None,
+    ) -> PatientProfile:
+        """Create or update patient profile (merge-append for arrays)."""
+        payload: dict[str, Any] = {}
+        if chronic_conditions is not None:
+            payload["chronic_conditions"] = chronic_conditions
+        if current_medications is not None:
+            payload["current_medications"] = current_medications
+        if allergies is not None:
+            payload["allergies"] = allergies
+        if risk_factors is not None:
+            payload["risk_factors"] = risk_factors
+        if family_history is not None:
+            payload["family_history"] = family_history
+        if smoking_status is not None:
+            payload["smoking_status"] = smoking_status
+        if alcohol_status is not None:
+            payload["alcohol_status"] = alcohol_status
+        return PatientProfile.from_dict(
+            await self._request("PUT", f"/v1/patients/{patient_id}/profile", json=payload)
+        )
+
+    async def list_patient_sessions(self, patient_id: str) -> list[dict[str, Any]]:
+        """List sessions for a patient."""
+        data = await self._request("GET", f"/v1/patients/{patient_id}/sessions")
+        return data.get("sessions", data) if isinstance(data, dict) else data
+
+    async def delete_patient(self, patient_id: str) -> dict[str, Any]:
+        """Delete patient and all associated data."""
+        return await self._request("DELETE", f"/v1/patients/{patient_id}")
+
+    # --- Admin ---
+
+    async def get_balance(self) -> BalanceResponse:
+        """Get current token balance."""
+        return BalanceResponse.from_dict(await self._request("GET", "/v1/admin/balance"))
+
+    async def get_usage(self, days: int = 30) -> UsageResponse:
+        """Get token usage for last N days."""
+        return UsageResponse.from_dict(await self._request("GET", f"/v1/admin/usage?days={days}"))
+
+    async def list_keys(self) -> list[dict[str, Any]]:
+        """List all API keys."""
+        return await self._request("GET", "/v1/admin/keys")
+
+    async def create_key(self, name: str) -> dict[str, Any]:
+        """Create a new API key."""
+        return await self._request("POST", "/v1/admin/keys", json={"name": name})
+
+    async def revoke_key(self, key_id: str) -> dict[str, Any]:
+        """Revoke an API key."""
+        return await self._request("DELETE", f"/v1/admin/keys/{key_id}")
+
+    # --- Convenience ---
+
+    async def run_assessment(
+        self,
+        chief_complaint: str,
+        age: int | None = None,
+        sex: str | None = None,
+        answers: dict[str, str] | None = None,
+        max_questions: int = 15,
+    ) -> ResultsResponse:
+        """
+        Run a full assessment end-to-end.
+        If answers is None, auto-skips all questions.
+        Cost: 1 + N*8 tokens (N = answered questions).
+        """
+        session = await self.create_session(chief_complaint=chief_complaint, age=age, sex=sex)
+        session_id = session.session_id
+        q = session.current_question
+        asked = 0
+
+        while q and asked < max_questions:
+            qid = q.question_id
+            if answers and qid in answers:
+                result = await self.answer(session_id, qid, raw_text=answers[qid])
+            else:
+                result = await self.answer(session_id, qid, skip=True)
+            asked += 1
+            if result.is_complete:
+                break
+            q = result.current_question
+
+        return await self.finalize(session_id)
+
+    async def close(self):
+        """Close the HTTP connection."""
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()

nessyapi_sdk-0.2.0/nessyapi_sdk/client.py

@@ -0,0 +1,269 @@
+"""
+NessyAPI Python SDK — synchronous client.
+
+Usage:
+    from nessyapi_sdk import NessyClient
+
+    with NessyClient(api_key="nsy_live_...") as client:
+        session = client.create_session("headache", age=35, sex="male")
+        result = client.answer(session.session_id, "q1", raw_text="3 days")
+        final = client.finalize(session.session_id)
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from nessyapi_sdk.models import (
+    AnswerResponse,
+    BalanceResponse,
+    PatientProfile,
+    ResultsResponse,
+    SessionResponse,
+    UsageResponse,
+)
+
+DEFAULT_BASE_URL = "https://nessyapi.bravemeadow-4ea62cad.northeurope.azurecontainerapps.io"
+_RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
+_MAX_RETRIES = 3
+
+
+class NessyAPIError(Exception):
+    """Raised on HTTP 4xx/5xx responses from NessyAPI."""
+
+    def __init__(self, status: int, body: dict[str, Any]):
+        self.status = status
+        self.body = body
+        detail = body.get("detail", body.get("error", f"HTTP {status}"))
+        super().__init__(f"NessyAPI error {status}: {detail}")
+
+
+class NessyClient:
+    """Synchronous NessyAPI client with retry and typed responses."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = _MAX_RETRIES,
+    ):
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    def _request(self, method: str, path: str, **kwargs) -> dict[str, Any]:
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = self._client.request(method, path, **kwargs)
+            except httpx.TransportError as e:
+                last_exc = e
+                if attempt < self._max_retries:
+                    time.sleep(2 ** attempt)
+                    continue
+                raise
+
+            if resp.status_code < 400:
+                return resp.json()
+
+            if resp.status_code in _RETRYABLE_STATUSES and attempt < self._max_retries:
+                retry_after = resp.headers.get("Retry-After")
+                wait = float(retry_after) if retry_after else 2 ** attempt
+                time.sleep(min(wait, 60))
+                continue
+
+            try:
+                body = resp.json()
+            except Exception:
+                body = {"error": resp.text}
+            raise NessyAPIError(resp.status_code, body)
+
+        raise last_exc or NessyAPIError(500, {"error": "Max retries exceeded"})
+
+    # --- Session Lifecycle ---
+
+    def create_session(
+        self,
+        chief_complaint: str,
+        age: int | None = None,
+        sex: str | None = None,
+        free_text: str | None = None,
+    ) -> SessionResponse:
+        """Create a new clinical session. Cost: 1 token."""
+        payload: dict[str, Any] = {"chief_complaint": chief_complaint}
+        if age is not None:
+            payload["age"] = age
+        if sex is not None:
+            payload["sex"] = sex
+        if free_text is not None:
+            payload["free_text"] = free_text
+        return SessionResponse.from_dict(self._request("POST", "/v1/sessions", json=payload))
+
+    def route(self, session_id: str, text: str) -> AnswerResponse:
+        """Route free-text to clinical branch. Cost: 5 tokens."""
+        data = self._request("POST", f"/v1/sessions/{session_id}/route", json={"text": text})
+        return AnswerResponse.from_dict(data)
+
+    def answer(
+        self,
+        session_id: str,
+        question_id: str,
+        *,
+        raw_text: str | None = None,
+        extracted_fields: dict[str, Any] | None = None,
+        extracted_flags: list[str] | None = None,
+        skip: bool = False,
+    ) -> AnswerResponse:
+        """Submit a patient answer. Cost: 8 tokens (0 if skip)."""
+        payload: dict[str, Any] = {"question_id": question_id}
+        if raw_text is not None:
+            payload["raw_text"] = raw_text
+        if extracted_fields:
+            payload["extracted_fields"] = extracted_fields
+        if extracted_flags:
+            payload["extracted_flags"] = extracted_flags
+        if skip:
+            payload["skip"] = True
+        return AnswerResponse.from_dict(
+            self._request("POST", f"/v1/sessions/{session_id}/answer", json=payload)
+        )
+
+    def get_results(self, session_id: str) -> ResultsResponse:
+        """Get current differentials and triage. FREE."""
+        return ResultsResponse.from_dict(self._request("GET", f"/v1/sessions/{session_id}/results"))
+
+    def get_state(self, session_id: str) -> dict[str, Any]:
+        """Get session state. FREE."""
+        return self._request("GET", f"/v1/sessions/{session_id}/state")
+
+    def finalize(self, session_id: str) -> ResultsResponse:
+        """Finalize session and get full results. FREE."""
+        return ResultsResponse.from_dict(
+            self._request("POST", f"/v1/sessions/{session_id}/finalize")
+        )
+
+    # --- Patient Profiles ---
+
+    def get_patient(self, patient_id: str) -> PatientProfile:
+        """Get patient profile."""
+        return PatientProfile.from_dict(
+            self._request("GET", f"/v1/patients/{patient_id}/profile")
+        )
+
+    def update_patient(
+        self,
+        patient_id: str,
+        *,
+        chronic_conditions: list[str] | None = None,
+        current_medications: list[str] | None = None,
+        allergies: list[str] | None = None,
+        risk_factors: list[str] | None = None,
+        family_history: list[str] | None = None,
+        smoking_status: str | None = None,
+        alcohol_status: str | None = None,
+    ) -> PatientProfile:
+        """Create or update patient profile (merge-append for arrays)."""
+        payload: dict[str, Any] = {}
+        if chronic_conditions is not None:
+            payload["chronic_conditions"] = chronic_conditions
+        if current_medications is not None:
+            payload["current_medications"] = current_medications
+        if allergies is not None:
+            payload["allergies"] = allergies
+        if risk_factors is not None:
+            payload["risk_factors"] = risk_factors
+        if family_history is not None:
+            payload["family_history"] = family_history
+        if smoking_status is not None:
+            payload["smoking_status"] = smoking_status
+        if alcohol_status is not None:
+            payload["alcohol_status"] = alcohol_status
+        return PatientProfile.from_dict(
+            self._request("PUT", f"/v1/patients/{patient_id}/profile", json=payload)
+        )
+
+    def list_patient_sessions(self, patient_id: str) -> list[dict[str, Any]]:
+        """List sessions for a patient."""
+        data = self._request("GET", f"/v1/patients/{patient_id}/sessions")
+        return data.get("sessions", data) if isinstance(data, dict) else data
+
+    def delete_patient(self, patient_id: str) -> dict[str, Any]:
+        """Delete patient and all associated data."""
+        return self._request("DELETE", f"/v1/patients/{patient_id}")
+
+    # --- Admin ---
+
+    def get_balance(self) -> BalanceResponse:
+        """Get current token balance."""
+        return BalanceResponse.from_dict(self._request("GET", "/v1/admin/balance"))
+
+    def get_usage(self, days: int = 30) -> UsageResponse:
+        """Get token usage for last N days."""
+        return UsageResponse.from_dict(self._request("GET", f"/v1/admin/usage?days={days}"))
+
+    def list_keys(self) -> list[dict[str, Any]]:
+        """List all API keys."""
+        return self._request("GET", "/v1/admin/keys")
+
+    def create_key(self, name: str) -> dict[str, Any]:
+        """Create a new API key."""
+        return self._request("POST", "/v1/admin/keys", json={"name": name})
+
+    def revoke_key(self, key_id: str) -> dict[str, Any]:
+        """Revoke an API key."""
+        return self._request("DELETE", f"/v1/admin/keys/{key_id}")
+
+    # --- Convenience ---
+
+    def run_assessment(
+        self,
+        chief_complaint: str,
+        age: int | None = None,
+        sex: str | None = None,
+        answers: dict[str, str] | None = None,
+        max_questions: int = 15,
+    ) -> ResultsResponse:
+        """
+        Run a full assessment end-to-end.
+        If answers is None, auto-skips all questions.
+        Cost: 1 + N*8 tokens (N = answered questions).
+        """
+        session = self.create_session(chief_complaint=chief_complaint, age=age, sex=sex)
+        session_id = session.session_id
+        q = session.current_question
+        asked = 0
+
+        while q and asked < max_questions:
+            qid = q.question_id
+            if answers and qid in answers:
+                result = self.answer(session_id, qid, raw_text=answers[qid])
+            else:
+                result = self.answer(session_id, qid, skip=True)
+            asked += 1
+            if result.is_complete:
+                break
+            q = result.current_question
+
+        return self.finalize(session_id)
+
+    def close(self):
+        """Close the HTTP connection."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

nessyapi_sdk-0.2.0/nessyapi_sdk/models.py

@@ -0,0 +1,163 @@
+"""Typed response models for NessyAPI SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Question:
+    question_id: str
+    text: str
+    answer_type: str = ""
+    options: list[str] = field(default_factory=list)
+    branch: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any] | None) -> Question | None:
+        if not d:
+            return None
+        return cls(
+            question_id=d.get("question_id", ""),
+            text=d.get("text", ""),
+            answer_type=d.get("answer_type", ""),
+            options=d.get("options", []),
+            branch=d.get("branch", ""),
+        )
+
+
+@dataclass
+class Differential:
+    diagnosis: str
+    probability: float
+    icd10: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Differential:
+        return cls(
+            diagnosis=d.get("diagnosis", ""),
+            probability=d.get("probability", 0.0),
+            icd10=d.get("icd10", ""),
+        )
+
+
+@dataclass
+class SessionResponse:
+    session_id: str
+    status: str
+    current_question: Question | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> SessionResponse:
+        return cls(
+            session_id=d.get("session_id", ""),
+            status=d.get("status", ""),
+            current_question=Question.from_dict(d.get("current_question")),
+            raw=d,
+        )
+
+
+@dataclass
+class AnswerResponse:
+    session_id: str
+    is_complete: bool
+    current_question: Question | None = None
+    questions_asked: int = 0
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> AnswerResponse:
+        return cls(
+            session_id=d.get("session_id", ""),
+            is_complete=d.get("is_complete", False),
+            current_question=Question.from_dict(d.get("current_question")),
+            questions_asked=d.get("questions_asked", 0),
+            raw=d,
+        )
+
+
+@dataclass
+class ResultsResponse:
+    session_id: str
+    triage_level: str
+    differentials: list[Differential]
+    red_flags: list[str]
+    recommendations: list[str] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ResultsResponse:
+        return cls(
+            session_id=d.get("session_id", ""),
+            triage_level=d.get("triage_level", d.get("triage", {}).get("level", "")),
+            differentials=[
+                Differential.from_dict(dx)
+                for dx in d.get("differentials", [])
+            ],
+            red_flags=d.get("red_flags", []),
+            recommendations=d.get("recommendations", []),
+            raw=d,
+        )
+
+
+@dataclass
+class BalanceResponse:
+    balance: int
+    lifetime_used: int
+    tier: str
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> BalanceResponse:
+        return cls(
+            balance=d.get("balance", 0),
+            lifetime_used=d.get("lifetime_used", 0),
+            tier=d.get("tier", ""),
+            raw=d,
+        )
+
+
+@dataclass
+class UsageResponse:
+    total_tokens: int
+    days: int
+    daily: list[dict[str, Any]] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> UsageResponse:
+        return cls(
+            total_tokens=d.get("total_tokens", 0),
+            days=d.get("days", 30),
+            daily=d.get("daily", []),
+            raw=d,
+        )
+
+
+@dataclass
+class PatientProfile:
+    partner_patient_id: str
+    chronic_conditions: list[str] = field(default_factory=list)
+    current_medications: list[str] = field(default_factory=list)
+    allergies: list[str] = field(default_factory=list)
+    risk_factors: list[str] = field(default_factory=list)
+    family_history: list[str] = field(default_factory=list)
+    smoking_status: str = ""
+    alcohol_status: str = ""
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> PatientProfile:
+        return cls(
+            partner_patient_id=d.get("partner_patient_id", ""),
+            chronic_conditions=d.get("chronic_conditions", []),
+            current_medications=d.get("current_medications", []),
+            allergies=d.get("allergies", []),
+            risk_factors=d.get("risk_factors", []),
+            family_history=d.get("family_history", []),
+            smoking_status=d.get("smoking_status", ""),
+            alcohol_status=d.get("alcohol_status", ""),
+            raw=d,
+        )

nessyapi_sdk-0.2.0/nessyapi_sdk/webhook.py

@@ -0,0 +1,55 @@
+"""
+Webhook signature verification helper.
+
+Usage:
+    from nessyapi_sdk import verify_webhook_signature
+
+    # In your webhook handler:
+    is_valid = verify_webhook_signature(
+        payload=request.body,
+        secret="your-signing-secret",
+        signature=request.headers["X-NessyAPI-Signature-256"],
+    )
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def verify_webhook_signature(
+    payload: bytes,
+    secret: str,
+    signature: str,
+    timestamp: str | None = None,
+) -> bool:
+    """
+    Verify a NessyAPI webhook signature.
+
+    Args:
+        payload: Raw request body bytes
+        secret: Your webhook signing secret
+        signature: Value of X-NessyAPI-Signature-256 header
+        timestamp: Value of X-NessyAPI-Timestamp header (required for
+                   replay-safe verification — the server includes the
+                   timestamp in the signed content)
+
+    Returns:
+        True if signature is valid
+    """
+    if not signature.startswith("sha256="):
+        return False
+
+    # The server signs: payload + "." + timestamp (see signer.py)
+    data = payload
+    if timestamp:
+        data = payload + b"." + timestamp.encode("utf-8")
+
+    expected = "sha256=" + hmac.new(
+        secret.encode("utf-8"),
+        data,
+        hashlib.sha256,
+    ).hexdigest()
+
+    return hmac.compare_digest(expected, signature)

nessyapi_sdk-0.2.0/nessyapi_sdk.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: nessyapi-sdk
+Version: 0.2.0
+Summary: Python SDK for NessyAPI — Clinical Decision Support API
+Author-email: "HealthyNess.cz" <dev@healthyness.cz>
+License: MIT
+Project-URL: Homepage, https://healthyness.cz
+Project-URL: Documentation, https://github.com/jachymvrtiskaHN/NessyAPI/tree/master/sdk
+Project-URL: Repository, https://github.com/jachymvrtiskaHN/NessyAPI
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# NessyAPI Python SDK
+
+Python SDK for [NessyAPI](https://healthyness.cz) — Clinical Decision Support API.
+
+## Install
+
+```bash
+pip install nessyapi-sdk
+```
+
+## Quick Start
+
+```python
+from nessyapi_sdk import NessyClient
+
+with NessyClient(api_key="nsy_live_...") as client:
+    # Run a full assessment
+    results = client.run_assessment("headache", age=35, sex="male")
+    
+    print(f"Triage: {results.triage_level}")
+    for dx in results.differentials:
+        print(f"  {dx.diagnosis}: {dx.probability:.0%}")
+```
+
+## Async
+
+```python
+from nessyapi_sdk import AsyncNessyClient
+
+async with AsyncNessyClient(api_key="nsy_live_...") as client:
+    session = await client.create_session("chest_pain", age=55, sex="male")
+    result = await client.answer(session.session_id, "q1", raw_text="pressure pain")
+    final = await client.finalize(session.session_id)
+```
+
+## Features
+
+- Sync and async clients
+- Typed response models (dataclasses)
+- Automatic retry with exponential backoff (429, 5xx)
+- Patient profile management
+- Webhook signature verification
+
+## Links
+
+- [API Reference](https://github.com/jachymvrtiskaHN/NessyAPI/blob/master/docs/api-reference.md)
+- [SDK Guide](https://github.com/jachymvrtiskaHN/NessyAPI/blob/master/docs/sdk-guide.md)

nessyapi_sdk-0.2.0/nessyapi_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+nessyapi_sdk/__init__.py
+nessyapi_sdk/async_client.py
+nessyapi_sdk/client.py
+nessyapi_sdk/models.py
+nessyapi_sdk/webhook.py
+nessyapi_sdk.egg-info/PKG-INFO
+nessyapi_sdk.egg-info/SOURCES.txt
+nessyapi_sdk.egg-info/dependency_links.txt
+nessyapi_sdk.egg-info/requires.txt
+nessyapi_sdk.egg-info/top_level.txt
+tests/test_live.py

nessyapi_sdk-0.2.0/nessyapi_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nessyapi_sdk-0.2.0/nessyapi_sdk.egg-info/requires.txt

@@ -0,0 +1,5 @@
+httpx>=0.27
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21

nessyapi_sdk-0.2.0/nessyapi_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+nessyapi_sdk

nessyapi_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "nessyapi-sdk"
+version = "0.2.0"
+description = "Python SDK for NessyAPI — Clinical Decision Support API"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "HealthyNess.cz", email = "dev@healthyness.cz"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Healthcare Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21"]
+
+[project.urls]
+Homepage = "https://healthyness.cz"
+Documentation = "https://github.com/jachymvrtiskaHN/NessyAPI/tree/master/sdk"
+Repository = "https://github.com/jachymvrtiskaHN/NessyAPI"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["nessyapi_sdk*"]

nessyapi_sdk-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nessyapi_sdk-0.2.0/tests/test_live.py

@@ -0,0 +1,168 @@
+"""
+SDK live API tests.
+
+Run with:
+    NESSYAPI_URL=https://nessyapi.xxx.northeurope.azurecontainerapps.io \
+    NESSYAPI_KEY=nsy_live_xxx \
+    pytest sdk/tests/test_live.py -v
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import sys
+
+import pytest
+
+# Add SDK to path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from nessyapi_sdk import NessyClient, verify_webhook_signature
+
+API_URL = os.environ.get("NESSYAPI_URL", "")
+API_KEY = os.environ.get("NESSYAPI_KEY", "")
+
+pytestmark = pytest.mark.skipif(
+    not API_URL or not API_KEY,
+    reason="NESSYAPI_URL and NESSYAPI_KEY required",
+)
+
+
+@pytest.fixture
+def client():
+    c = NessyClient(api_key=API_KEY, base_url=API_URL, timeout=30)
+    yield c
+    c.close()
+
+
+# ---------------------------------------------------------------------------
+# Health
+# ---------------------------------------------------------------------------
+
+
+def test_health():
+    """Health endpoint is public and returns 200."""
+    import httpx
+
+    r = httpx.get(f"{API_URL}/health", timeout=10)
+    assert r.status_code == 200
+    data = r.json()
+    assert data.get("engine_ready") is True
+
+
+# ---------------------------------------------------------------------------
+# Balance & Admin
+# ---------------------------------------------------------------------------
+
+
+def test_balance(client):
+    b = client.get_balance()
+    assert b["balance"] >= 0
+    assert "tier" in b
+
+
+def test_list_keys(client):
+    keys = client.list_keys()
+    assert isinstance(keys, list)
+    assert len(keys) > 0
+
+
+# ---------------------------------------------------------------------------
+# Session Lifecycle
+# ---------------------------------------------------------------------------
+
+
+def test_create_session(client):
+    s = client.create_session(chief_complaint="headache", age=30, sex="female")
+    assert "session_id" in s
+    assert s["current_question"] is not None
+
+
+def test_full_session_lifecycle(client):
+    """Create -> answer -> results (FREE) -> finalize."""
+    s = client.create_session(chief_complaint="chest_pain", age=55, sex="male")
+    sid = s["session_id"]
+    qid = s["current_question"]["question_id"]
+
+    # Answer one question
+    a = client.answer(sid, qid, extracted_fields={"quality": "crushing"})
+    assert a["questions_asked"] >= 1
+
+    # Results (FREE — 0 tokens)
+    r = client.get_results(sid)
+    assert len(r["differentials"]) > 0
+
+    # Finalize
+    f = client.finalize(sid)
+    assert f["status"] == "finalized"
+
+
+def test_session_state(client):
+    """get_state returns active session info."""
+    s = client.create_session(chief_complaint="headache", age=25, sex="male")
+    sid = s["session_id"]
+
+    state = client.get_state(sid)
+    assert state["status"] == "active"
+    assert state["session_id"] == sid
+
+
+def test_answer_with_raw_text(client):
+    """Answer using raw_text instead of extracted_fields."""
+    s = client.create_session(chief_complaint="headache", age=40, sex="female")
+    sid = s["session_id"]
+    qid = s["current_question"]["question_id"]
+
+    a = client.answer(sid, qid, raw_text="It started two days ago, throbbing pain")
+    assert a["questions_asked"] >= 1
+
+
+def test_answer_skip(client):
+    """Skipping a question advances the session."""
+    s = client.create_session(chief_complaint="headache", age=35, sex="male")
+    sid = s["session_id"]
+    qid = s["current_question"]["question_id"]
+
+    a = client.answer(sid, qid, skip=True)
+    assert a["questions_asked"] >= 1
+
+
+# ---------------------------------------------------------------------------
+# Convenience method
+# ---------------------------------------------------------------------------
+
+
+def test_run_assessment(client):
+    """Test the convenience run_assessment method (auto-skip all questions)."""
+    result = client.run_assessment(chief_complaint="headache", age=40, sex="male")
+    assert result["status"] == "finalized"
+    assert result.get("primary_diagnosis") is not None
+
+
+# ---------------------------------------------------------------------------
+# Webhook Signature (offline — no API call needed)
+# ---------------------------------------------------------------------------
+
+
+def test_webhook_signature_verification():
+    """Test the SDK's webhook signature verification helper."""
+    payload = b'{"event": "session.finalized", "session_id": "abc123"}'
+    secret = "test-secret-123"
+
+    sig = "sha256=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
+
+    assert verify_webhook_signature(payload, secret, sig) is True
+    assert verify_webhook_signature(payload, "wrong-secret", sig) is False
+    assert verify_webhook_signature(b"tampered", secret, sig) is False
+
+
+def test_webhook_signature_rejects_invalid_format():
+    """Signatures without sha256= prefix are rejected."""
+    payload = b'{"event": "test"}'
+    secret = "s"
+    raw_hash = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
+
+    assert verify_webhook_signature(payload, secret, raw_hash) is False
+    assert verify_webhook_signature(payload, secret, f"md5={raw_hash}") is False