stresszero 1.0.0__tar.gz

stresszero-1.0.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: stresszero
+Version: 1.0.0
+Summary: Official Python SDK for StressZero Intelligence API — Burnout risk scoring for entrepreneurs
+Project-URL: Homepage, https://stresszeroentrepreneur.fr/intelligence-api
+Project-URL: Documentation, https://stresszeroentrepreneur.fr/docs
+Project-URL: Repository, https://github.com/StressZeroEntrepreneur/stresszero-sdk-python
+Project-URL: Issues, https://github.com/StressZeroEntrepreneur/stresszero-sdk-python/issues
+Author-email: Emmanuel Gomes Soares <hello@stresszeroentrepreneur.fr>
+License-Expression: MIT
+Keywords: api,burnout,entrepreneur,scoring,sdk,stress,wellness
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# StressZero Python SDK
+
+Official Python SDK for [StressZero Intelligence API](https://stresszeroentrepreneur.fr/intelligence-api) — Burnout risk scoring for entrepreneurs.
+
+## Installation
+
+```bash
+pip install stresszero
+```
+
+## Quick Start
+
+```python
+from stresszero import StressZero, ResponseItem, AnalysisContext
+
+sz = StressZero("sz_live_your_key_here")
+
+# Quick 3-score check
+result = sz.quick_check(physical=65, emotional=70, effectiveness=55)
+if result.ok:
+    print(f"Score: {result.data['score']['total']}/100")
+    print(f"Risk: {result.data['risk']['level']}")
+
+# Full analysis
+result = sz.analyze_burnout(
+    responses=[
+        ResponseItem("physical", "sleep_quality", 65, weight=3),
+        ResponseItem("emotional", "motivation", 70, weight=2),
+        ResponseItem("effectiveness", "productivity", 55, weight=2),
+    ],
+    context=AnalysisContext(profession="entrepreneur", hours_per_week=55),
+)
+
+# Predictive scoring (J+30)
+from stresszero.types import PredictiveContext
+
+result = sz.analyze_burnout_with_prediction(
+    responses=[
+        ResponseItem("physical", "sleep", 65, weight=3),
+        ResponseItem("emotional", "stress", 70, weight=2),
+        ResponseItem("effectiveness", "focus", 55, weight=2),
+    ],
+    predictive_context=PredictiveContext(
+        sleep_hours=6,
+        exercise_days_per_week=1,
+        has_support_network=False,
+    ),
+)
+if result.ok:
+    pred = result.data["prediction"]
+    print(f"Score J+30: {pred['prediction']['score_j30']}")
+    print(f"Trajectory: {pred['prediction']['trajectory']}")
+```
+
+## Sandbox Testing
+
+Use `sz_test_` prefixed keys for sandbox mode (no DB, no quota):
+
+```python
+sz = StressZero("sz_test_free")  # Free tier sandbox
+sz = StressZero("sz_test_pro")   # Pro tier sandbox
+```
+
+## API Reference
+
+| Method | Tier | Description |
+|--------|------|-------------|
+| `analyze_burnout()` | Free+ | Individual burnout scoring |
+| `analyze_burnout_with_prediction()` | Free+ | Scoring + J+30 prediction |
+| `analyze_team()` | Starter+ | Team analysis |
+| `generate_report()` | Starter+ | Detailed report |
+| `quick_check()` | Free+ | Quick 3-score check |
+| `health()` | Public | API health status |
+
+## License
+
+MIT — [StressZero Entrepreneur](https://stresszeroentrepreneur.fr)

stresszero-1.0.0/README.md

@@ -0,0 +1,77 @@
+# StressZero Python SDK
+
+Official Python SDK for [StressZero Intelligence API](https://stresszeroentrepreneur.fr/intelligence-api) — Burnout risk scoring for entrepreneurs.
+
+## Installation
+
+```bash
+pip install stresszero
+```
+
+## Quick Start
+
+```python
+from stresszero import StressZero, ResponseItem, AnalysisContext
+
+sz = StressZero("sz_live_your_key_here")
+
+# Quick 3-score check
+result = sz.quick_check(physical=65, emotional=70, effectiveness=55)
+if result.ok:
+    print(f"Score: {result.data['score']['total']}/100")
+    print(f"Risk: {result.data['risk']['level']}")
+
+# Full analysis
+result = sz.analyze_burnout(
+    responses=[
+        ResponseItem("physical", "sleep_quality", 65, weight=3),
+        ResponseItem("emotional", "motivation", 70, weight=2),
+        ResponseItem("effectiveness", "productivity", 55, weight=2),
+    ],
+    context=AnalysisContext(profession="entrepreneur", hours_per_week=55),
+)
+
+# Predictive scoring (J+30)
+from stresszero.types import PredictiveContext
+
+result = sz.analyze_burnout_with_prediction(
+    responses=[
+        ResponseItem("physical", "sleep", 65, weight=3),
+        ResponseItem("emotional", "stress", 70, weight=2),
+        ResponseItem("effectiveness", "focus", 55, weight=2),
+    ],
+    predictive_context=PredictiveContext(
+        sleep_hours=6,
+        exercise_days_per_week=1,
+        has_support_network=False,
+    ),
+)
+if result.ok:
+    pred = result.data["prediction"]
+    print(f"Score J+30: {pred['prediction']['score_j30']}")
+    print(f"Trajectory: {pred['prediction']['trajectory']}")
+```
+
+## Sandbox Testing
+
+Use `sz_test_` prefixed keys for sandbox mode (no DB, no quota):
+
+```python
+sz = StressZero("sz_test_free")  # Free tier sandbox
+sz = StressZero("sz_test_pro")   # Pro tier sandbox
+```
+
+## API Reference
+
+| Method | Tier | Description |
+|--------|------|-------------|
+| `analyze_burnout()` | Free+ | Individual burnout scoring |
+| `analyze_burnout_with_prediction()` | Free+ | Scoring + J+30 prediction |
+| `analyze_team()` | Starter+ | Team analysis |
+| `generate_report()` | Starter+ | Detailed report |
+| `quick_check()` | Free+ | Quick 3-score check |
+| `health()` | Public | API health status |
+
+## License
+
+MIT — [StressZero Entrepreneur](https://stresszeroentrepreneur.fr)

stresszero-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stresszero"
+version = "1.0.0"
+description = "Official Python SDK for StressZero Intelligence API — Burnout risk scoring for entrepreneurs"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+    { name = "Emmanuel Gomes Soares", email = "hello@stresszeroentrepreneur.fr" },
+]
+keywords = ["burnout", "stress", "api", "sdk", "wellness", "entrepreneur", "scoring"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[project.urls]
+Homepage = "https://stresszeroentrepreneur.fr/intelligence-api"
+Documentation = "https://stresszeroentrepreneur.fr/docs"
+Repository = "https://github.com/StressZeroEntrepreneur/stresszero-sdk-python"
+Issues = "https://github.com/StressZeroEntrepreneur/stresszero-sdk-python/issues"

stresszero-1.0.0/stresszero/__init__.py

@@ -0,0 +1,34 @@
+"""StressZero SDK — Official Python SDK for StressZero Intelligence API."""
+
+from .client import StressZero
+from .types import (
+    Dimension,
+    RiskLevel,
+    Language,
+    ResponseItem,
+    AnalysisContext,
+    AnalysisOptions,
+    AnalysisResult,
+    ReportResult,
+    TeamAnalysisResult,
+    PredictiveResult,
+    HealthResult,
+    ApiResponse,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "StressZero",
+    "Dimension",
+    "RiskLevel",
+    "Language",
+    "ResponseItem",
+    "AnalysisContext",
+    "AnalysisOptions",
+    "AnalysisResult",
+    "ReportResult",
+    "TeamAnalysisResult",
+    "PredictiveResult",
+    "HealthResult",
+    "ApiResponse",
+]

stresszero-1.0.0/stresszero/client.py

@@ -0,0 +1,259 @@
+"""StressZero API client."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .types import (
+    AnalysisContext,
+    AnalysisOptions,
+    ApiResponse,
+    HealthResult,
+    Language,
+    PredictiveContext,
+    PreviousScore,
+    ResponseItem,
+)
+
+
+class StressZero:
+    """Official Python client for StressZero Intelligence API.
+
+    Example::
+
+        from stresszero import StressZero, ResponseItem
+
+        sz = StressZero("sz_live_your_key_here")
+
+        result = sz.analyze_burnout(
+            responses=[
+                ResponseItem("physical", "sleep", 65, weight=3),
+                ResponseItem("emotional", "motivation", 70, weight=2),
+                ResponseItem("effectiveness", "productivity", 55, weight=2),
+            ],
+            context=AnalysisContext(profession="entrepreneur", hours_per_week=55),
+        )
+
+        if result.ok:
+            print(result.data["score"]["total"])
+            print(result.data["risk"]["level"])
+
+    Docs: https://stresszeroentrepreneur.fr/intelligence-api
+    """
+
+    BASE_URL = "https://stresszeroentrepreneur.fr"
+    VERSION = "1.0.0"
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        if not api_key or not (api_key.startswith("sz_live_") or api_key.startswith("sz_test_")):
+            raise ValueError(
+                "Invalid API key. Must start with 'sz_live_' or 'sz_test_'. "
+                "Get your free key at: https://stresszeroentrepreneur.fr/intelligence-api"
+            )
+
+        self._api_key = api_key
+        self._base_url = (base_url or self.BASE_URL).rstrip("/")
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"stresszero-python/{self.VERSION}",
+            },
+        )
+
+    def _request(self, method: str, path: str, json: Optional[Dict[str, Any]] = None) -> ApiResponse:
+        try:
+            resp = self._client.request(method, path, json=json)
+            data = resp.json()
+            return ApiResponse(
+                success=data.get("success", False),
+                data=data.get("data"),
+                error=data.get("error"),
+                meta=data.get("meta"),
+            )
+        except httpx.TimeoutException:
+            return ApiResponse(success=False, error={"message": "Request timed out"})
+        except Exception as e:
+            return ApiResponse(success=False, error={"message": str(e)})
+
+    def analyze_burnout(
+        self,
+        responses: List[ResponseItem],
+        *,
+        context: Optional[AnalysisContext] = None,
+        options: Optional[AnalysisOptions] = None,
+    ) -> ApiResponse:
+        """Score burnout risk across 3 dimensions (physical, emotional, effectiveness).
+
+        Args:
+            responses: List of ResponseItem (min 3, max 20).
+            context: Professional context (profession, hours, experience).
+            options: Output options (language, recommendations, dimensions).
+
+        Returns:
+            ApiResponse with score, risk, recommendations, suggested product.
+        """
+        payload: Dict[str, Any] = {
+            "responses": [asdict(r) for r in responses],
+        }
+        if context:
+            payload["context"] = {k: v for k, v in asdict(context).items() if v is not None}
+        if options:
+            payload["options"] = {k: v for k, v in asdict(options).items() if v is not None}
+
+        return self._request("POST", "/api/v1/analyze-burnout", json=payload)
+
+    def analyze_burnout_with_prediction(
+        self,
+        responses: List[ResponseItem],
+        *,
+        context: Optional[AnalysisContext] = None,
+        predictive_context: Optional[PredictiveContext] = None,
+        previous_scores: Optional[List[PreviousScore]] = None,
+        language: Language = "fr",
+    ) -> ApiResponse:
+        """Analyze burnout with J+30 predictive trajectory.
+
+        Args:
+            responses: List of ResponseItem.
+            context: Professional context.
+            predictive_context: Lifestyle factors for prediction.
+            previous_scores: Historical scores for trend detection.
+            language: Response language ('fr' or 'en').
+
+        Returns:
+            ApiResponse with score, risk, recommendations + prediction.
+        """
+        payload: Dict[str, Any] = {
+            "responses": [asdict(r) for r in responses],
+            "options": {"include_prediction": True, "language": language},
+        }
+        if context:
+            payload["context"] = {k: v for k, v in asdict(context).items() if v is not None}
+        if predictive_context:
+            payload["predictive_context"] = {k: v for k, v in asdict(predictive_context).items() if v is not None}
+        if previous_scores:
+            payload["previous_scores"] = [asdict(s) for s in previous_scores]
+
+        return self._request("POST", "/api/v1/analyze-burnout", json=payload)
+
+    def analyze_team(
+        self,
+        members: List[Dict[str, Any]],
+        *,
+        team_name: Optional[str] = None,
+        anonymize: bool = True,
+        language: Language = "fr",
+    ) -> ApiResponse:
+        """Analyze burnout risk across a team. Requires Starter+ tier.
+
+        Args:
+            members: List of team member data (responses + context).
+            team_name: Optional team name.
+            anonymize: Anonymize member IDs in response.
+            language: Response language.
+
+        Returns:
+            ApiResponse with team stats, distribution, alerts, recommendations.
+        """
+        payload: Dict[str, Any] = {
+            "members": members,
+            "options": {"anonymize": anonymize, "language": language},
+        }
+        if team_name:
+            payload["team_name"] = team_name
+
+        return self._request("POST", "/api/v1/analyze-team", json=payload)
+
+    def generate_report(
+        self,
+        responses: List[ResponseItem],
+        *,
+        context: Optional[Dict[str, Any]] = None,
+        language: Language = "fr",
+        format: str = "json",
+    ) -> ApiResponse:
+        """Generate a detailed burnout report. Requires Starter+ tier.
+
+        Args:
+            responses: List of ResponseItem.
+            context: Report context (profession, company, employee name).
+            language: Report language.
+            format: Output format ('json' or 'html').
+
+        Returns:
+            ApiResponse with full report (summary, dimensions, action plan, resources).
+        """
+        payload: Dict[str, Any] = {
+            "responses": [asdict(r) for r in responses],
+            "language": language,
+            "format": format,
+        }
+        if context:
+            payload["context"] = context
+
+        return self._request("POST", "/api/v1/generate-report", json=payload)
+
+    def quick_check(
+        self,
+        physical: int,
+        emotional: int,
+        effectiveness: int,
+        *,
+        profession: Optional[str] = None,
+        hours_per_week: Optional[int] = None,
+    ) -> ApiResponse:
+        """Quick 3-score burnout check.
+
+        Args:
+            physical: Physical exhaustion score (0-100).
+            emotional: Emotional depletion score (0-100).
+            effectiveness: Reduced effectiveness score (0-100).
+
+        Returns:
+            ApiResponse with score, risk level, recommendations.
+        """
+        responses = [
+            ResponseItem("physical", "overall", physical, weight=2),
+            ResponseItem("emotional", "overall", emotional, weight=2),
+            ResponseItem("effectiveness", "overall", effectiveness, weight=2),
+        ]
+        context = AnalysisContext(profession=profession, hours_per_week=hours_per_week)
+        return self.analyze_burnout(responses, context=context)
+
+    def health(self) -> HealthResult:
+        """Check API health status (no auth required).
+
+        Returns:
+            HealthResult with status, version, checks.
+        """
+        resp = httpx.get(f"{self._base_url}/api/v1/health", timeout=10)
+        data = resp.json()
+        return HealthResult(
+            status=data.get("status", "unknown"),
+            version=data.get("version", ""),
+            timestamp=data.get("timestamp", ""),
+            latency_ms=data.get("latency_ms", 0),
+            checks=data.get("checks", {}),
+        )
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

stresszero-1.0.0/stresszero/types.py

@@ -0,0 +1,156 @@
+"""Type definitions for StressZero SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional, Union
+
+
+Dimension = Literal["physical", "emotional", "effectiveness"]
+RiskLevel = Literal["low", "moderate", "high", "critical"]
+Language = Literal["fr", "en"]
+Trajectory = Literal["improving", "stable", "worsening", "critical_acceleration"]
+
+
+@dataclass
+class ResponseItem:
+    dimension: Dimension
+    question_id: str
+    value: int
+    weight: int = 1
+
+
+@dataclass
+class AnalysisContext:
+    profession: Optional[str] = None
+    hours_per_week: Optional[int] = None
+    team_size: Optional[int] = None
+    years_experience: Optional[int] = None
+
+
+@dataclass
+class AnalysisOptions:
+    include_recommendations: bool = True
+    include_dimensions: bool = True
+    include_prediction: bool = False
+    language: Language = "fr"
+
+
+@dataclass
+class PredictiveContext:
+    has_support_network: Optional[bool] = None
+    has_morning_routine: Optional[bool] = None
+    exercise_days_per_week: Optional[int] = None
+    sleep_hours: Optional[float] = None
+
+
+@dataclass
+class PreviousScore:
+    physical: int
+    emotional: int
+    effectiveness: int
+    measured_at: str
+
+
+@dataclass
+class DimensionScore:
+    physical: int
+    emotional: int
+    effectiveness: int
+
+
+@dataclass
+class RiskAssessment:
+    level: RiskLevel
+    factors: List[str]
+    urgency: int
+
+
+@dataclass
+class SuggestedProduct:
+    id: str
+    url: str
+
+
+@dataclass
+class PredictiveResult:
+    prediction: Dict[str, Any]
+    risk_factors: List[Dict[str, Any]]
+    intervention_urgency: Dict[str, Any]
+
+
+@dataclass
+class AnalysisResult:
+    score: Dict[str, Any]
+    risk: Dict[str, Any]
+    recommendations: Optional[List[str]] = None
+    suggested_product: Optional[Dict[str, str]] = None
+    disclaimer: Optional[str] = None
+    prediction: Optional[PredictiveResult] = None
+
+
+@dataclass
+class ReportResult:
+    report: Dict[str, Any]
+    summary: Dict[str, Any]
+    dimensions: Dict[str, Any]
+    action_plan: Dict[str, Any]
+    context_factors: Optional[Dict[str, Any]] = None
+    resources: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class TeamMember:
+    member_id: str
+    score: int
+    risk_level: RiskLevel
+    dimensions: DimensionScore
+
+
+@dataclass
+class TeamAnalysisResult:
+    team: Dict[str, Any]
+    distribution: Optional[Dict[str, int]] = None
+    department_breakdown: Optional[Dict[str, Any]] = None
+    alerts: List[str] = field(default_factory=list)
+    recommendations: List[str] = field(default_factory=list)
+    members: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class HealthResult:
+    status: str
+    version: str
+    timestamp: str
+    latency_ms: float
+    checks: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ApiMeta:
+    api_version: str
+    latency_ms: float
+    quota: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ApiResponse:
+    success: bool
+    data: Optional[Any] = None
+    error: Optional[Dict[str, Any]] = None
+    meta: Optional[ApiMeta] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.success
+
+    def raise_for_error(self) -> None:
+        if not self.success and self.error:
+            raise StressZeroError(self.error.get("message", "Unknown error"), self.error.get("status"))
+
+
+class StressZeroError(Exception):
+    def __init__(self, message: str, status: Optional[int] = None):
+        self.message = message
+        self.status = status
+        super().__init__(f"[{status}] {message}" if status else message)