deutero 0.2.0__py3-none-any.whl

deutero/__init__.py

@@ -0,0 +1,258 @@
+"""Deutero Python SDK — bindings for the Deutero Study Management API.
+
+Usage::
+
+    from deutero import Deutero
+
+    client = Deutero(api_key="your-api-key")
+    project = client.projects.create(name="Onboarding research")
+    study = client.studies.create(
+        project_id=project.id,
+        name="Why new users drop off",
+        survey_type="user_experience",
+    )
+"""
+
+from deutero import webhooks
+from deutero.client import AsyncDeutero, Deutero
+from deutero.exceptions import (
+    APIError,
+    AuthenticationError,
+    BadGatewayError,
+    ConflictError,
+    ConnectionError,
+    DeuteroError,
+    InsufficientCreditsError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    TimeoutError,
+    ValidationError,
+    WebhookVerificationError,
+)
+from deutero.models import (
+    AnalysisCategory,
+    AnalyzableQuestion,
+    AnalyzableQuestionsOut,
+    CapturedVariableOut,
+    Centroid,
+    CharacteristicQuestionOut,
+    CharacteristicsOut,
+    CharacteristicsSettingsOut,
+    CharacteristicValueOut,
+    ClusteringOut,
+    ClusterPoints,
+    CreditBalanceOut,
+    CreditCheckOut,
+    DecisionOutcomeOut,
+    EmbedKeyListOut,
+    EmbedMetadataItem,
+    EmbedSnippetOut,
+    EthicsCheck,
+    FlowCheckError,
+    FlowDocument,
+    FlowEdge,
+    FlowNode,
+    FlowSignalOut,
+    FlowSignalsOut,
+    GeneratedQuestionsOut,
+    GraphCheckOut,
+    GraphModeOut,
+    GraphOut,
+    InterviewDetailListOut,
+    InterviewDetailOut,
+    InterviewEffectsOut,
+    InterviewListOut,
+    InterviewSummary,
+    InterviewTranscript,
+    IssueLocation,
+    IssueOut,
+    LanguageIssues,
+    LatestValidationOut,
+    ModelTier,
+    NodeFetchOut,
+    NodeType,
+    OptimalClustersOut,
+    OptionCount,
+    OptionsResponsesOut,
+    PatchOp,
+    PauseOut,
+    PersonaGenerateOut,
+    PersonaListOut,
+    PersonaOut,
+    ProjectListOut,
+    ProjectOut,
+    PublicationStatusOut,
+    PublishOut,
+    QualificationOut,
+    QuestionImageOut,
+    QuestionListOut,
+    QuestionOut,
+    QuestionValidation,
+    RecruitmentOut,
+    RedundancyCheck,
+    ScaleConfig,
+    ScaleResponsesOut,
+    ScreeningOut,
+    ScreeningQuestionOut,
+    ScreeningSettingsOut,
+    SearchHit,
+    SearchMode,
+    SearchOut,
+    SignalDeliveryOut,
+    SimulationListOut,
+    SimulationOut,
+    SimulationStartOut,
+    StudyDraft,
+    StudyDraftFromSiteOut,
+    StudyListOut,
+    StudyOut,
+    StudyStatsOut,
+    StudySummary,
+    StudyType,
+    SuccessResponse,
+    TranscriptMessage,
+    TranscriptOut,
+    TranscriptsBulkOut,
+    ValidationOut,
+    ValidationRunOut,
+    WebhookCreatedOut,
+    WebhookDeleteOut,
+    WebhookDeliveryListOut,
+    WebhookDeliveryOut,
+    WebhookEventTypeListOut,
+    WebhookEventTypeOut,
+    WebhookListOut,
+    WebhookOut,
+    WebhookSecretOut,
+    WelcomeDraftOut,
+    WelcomeOut,
+    WelcomeTranslationListOut,
+    WelcomeTranslationOut,
+)
+
+__all__ = [
+    # Clients
+    "Deutero",
+    "AsyncDeutero",
+    # Exceptions
+    "DeuteroError",
+    "APIError",
+    "AuthenticationError",
+    "BadGatewayError",
+    "ConflictError",
+    "ConnectionError",
+    "InsufficientCreditsError",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "TimeoutError",
+    "ValidationError",
+    "WebhookVerificationError",
+    # Webhook payload handling
+    "webhooks",
+    # Enums
+    "AnalysisCategory",
+    "ModelTier",
+    "NodeType",
+    "SearchMode",
+    "StudyType",
+    # Models
+    "AnalyzableQuestion",
+    "AnalyzableQuestionsOut",
+    "CapturedVariableOut",
+    "Centroid",
+    "CharacteristicQuestionOut",
+    "CharacteristicValueOut",
+    "CharacteristicsOut",
+    "CharacteristicsSettingsOut",
+    "ClusterPoints",
+    "ClusteringOut",
+    "CreditBalanceOut",
+    "CreditCheckOut",
+    "DecisionOutcomeOut",
+    "EmbedKeyListOut",
+    "EmbedMetadataItem",
+    "EmbedSnippetOut",
+    "EthicsCheck",
+    "FlowCheckError",
+    "FlowDocument",
+    "FlowEdge",
+    "FlowNode",
+    "FlowSignalOut",
+    "FlowSignalsOut",
+    "GeneratedQuestionsOut",
+    "GraphCheckOut",
+    "GraphModeOut",
+    "GraphOut",
+    "InterviewDetailListOut",
+    "InterviewDetailOut",
+    "InterviewEffectsOut",
+    "InterviewListOut",
+    "InterviewSummary",
+    "InterviewTranscript",
+    "IssueLocation",
+    "IssueOut",
+    "LanguageIssues",
+    "LatestValidationOut",
+    "NodeFetchOut",
+    "OptimalClustersOut",
+    "OptionCount",
+    "OptionsResponsesOut",
+    "PatchOp",
+    "PauseOut",
+    "PersonaGenerateOut",
+    "PersonaListOut",
+    "PersonaOut",
+    "ProjectListOut",
+    "ProjectOut",
+    "PublicationStatusOut",
+    "PublishOut",
+    "QualificationOut",
+    "QuestionImageOut",
+    "QuestionListOut",
+    "QuestionOut",
+    "QuestionValidation",
+    "RecruitmentOut",
+    "RedundancyCheck",
+    "ScaleConfig",
+    "ScaleResponsesOut",
+    "ScreeningOut",
+    "ScreeningQuestionOut",
+    "ScreeningSettingsOut",
+    "SearchHit",
+    "SearchOut",
+    "SignalDeliveryOut",
+    "SimulationListOut",
+    "SimulationOut",
+    "SimulationStartOut",
+    "StudyDraft",
+    "StudyDraftFromSiteOut",
+    "StudyListOut",
+    "StudyOut",
+    "StudyStatsOut",
+    "StudySummary",
+    "SuccessResponse",
+    "TranscriptMessage",
+    "TranscriptOut",
+    "TranscriptsBulkOut",
+    "ValidationOut",
+    "ValidationRunOut",
+    "WebhookCreatedOut",
+    "WebhookDeleteOut",
+    "WebhookDeliveryListOut",
+    "WebhookDeliveryOut",
+    "WebhookEventTypeListOut",
+    "WebhookEventTypeOut",
+    "WebhookListOut",
+    "WebhookOut",
+    "WebhookSecretOut",
+    "WelcomeDraftOut",
+    "WelcomeOut",
+    "WelcomeTranslationListOut",
+    "WelcomeTranslationOut",
+]
+
+__version__ = "0.2.0"

deutero/_http.py

@@ -0,0 +1,217 @@
+"""Low-level HTTP transport for the Deutero SDK.
+
+Provides both synchronous and asynchronous HTTP clients backed by httpx.
+"""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime
+from typing import Any, Dict, Optional
+from uuid import UUID
+
+import httpx
+from pydantic import BaseModel
+
+from deutero.exceptions import ConnectionError, TimeoutError, raise_for_status
+
+_DEFAULT_TIMEOUT = 120.0
+_DEFAULT_BASE_URL = "https://dashboard.deutero.ai/study-api"
+_USER_AGENT = "deutero-python/0.2.0"
+
+
+def _build_headers(api_key: str, extra: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+    headers = {
+        "X-API-Key": api_key,
+        "User-Agent": _USER_AGENT,
+        "Accept": "application/json",
+    }
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def _parse_response(response: httpx.Response) -> Any:
+    request_id = response.headers.get("x-request-id")
+    if response.status_code == 204 or not response.content:
+        raise_for_status(response.status_code, None, request_id=request_id)
+        return None
+    try:
+        body = response.json()
+    except Exception:
+        body = response.text
+
+    raise_for_status(response.status_code, body, request_id=request_id)
+    return body
+
+
+class SyncHTTPClient:
+    """Synchronous HTTP client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._headers = _build_headers(api_key)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(
+            base_url=self._base_url,
+            headers=self._headers,
+            timeout=timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        try:
+            response = self._client.request(
+                method,
+                self._url(path),
+                json=json,
+                params=_clean_params(params),
+                headers=self._headers,
+            )
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"Failed to connect to {self._base_url}: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(f"Request to {path} timed out after {self._timeout}s") from exc
+
+        return _parse_response(response)
+
+    def _url(self, path: str) -> str:
+        # A caller-supplied httpx client may not carry our base URL.
+        return path if str(self._client.base_url) else self._base_url + path
+
+    def get(self, path: str, *, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, *, json: Optional[Any] = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("POST", path, json=json, params=params)
+
+    def put(self, path: str, *, json: Optional[Any] = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("PUT", path, json=json, params=params)
+
+    def patch(self, path: str, *, json: Optional[Any] = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("PATCH", path, json=json, params=params)
+
+    def delete(self, path: str, *, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("DELETE", path, params=params)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+
+class AsyncHTTPClient:
+    """Asynchronous HTTP client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._headers = _build_headers(api_key)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=self._headers,
+            timeout=timeout,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        try:
+            response = await self._client.request(
+                method,
+                self._url(path),
+                json=json,
+                params=_clean_params(params),
+                headers=self._headers,
+            )
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"Failed to connect to {self._base_url}: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(f"Request to {path} timed out after {self._timeout}s") from exc
+
+        return _parse_response(response)
+
+    def _url(self, path: str) -> str:
+        # A caller-supplied httpx client may not carry our base URL.
+        return path if str(self._client.base_url) else self._base_url + path
+
+    async def get(self, path: str, *, params: Optional[Dict[str, Any]] = None) -> Any:
+        return await self.request("GET", path, params=params)
+
+    async def post(self, path: str, *, json: Optional[Any] = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        return await self.request("POST", path, json=json, params=params)
+
+    async def put(self, path: str, *, json: Optional[Any] = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        return await self.request("PUT", path, json=json, params=params)
+
+    async def patch(self, path: str, *, json: Optional[Any] = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        return await self.request("PATCH", path, json=json, params=params)
+
+    async def delete(self, path: str, *, params: Optional[Dict[str, Any]] = None) -> Any:
+        return await self.request("DELETE", path, params=params)
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+
+def _clean_params(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Remove None values from query parameters and stringify the rest."""
+    if params is None:
+        return None
+    return {k: _param_value(v) for k, v in params.items() if v is not None}
+
+
+def _param_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, enum.Enum):
+        return str(value.value)
+    return value if isinstance(value, str) else str(value)
+
+
+def compact(**fields: Any) -> Dict[str, Any]:
+    """Build a JSON body from keyword arguments, dropping those left as ``None``."""
+    return {k: _jsonable(v) for k, v in fields.items() if v is not None}
+
+
+def _jsonable(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json", by_alias=True, exclude_none=True)
+    if isinstance(value, UUID):
+        return str(value)
+    if isinstance(value, enum.Enum):
+        return value.value
+    if isinstance(value, list):
+        return [_jsonable(v) for v in value]
+    return value

deutero/client.py

@@ -0,0 +1,215 @@
+"""Deutero API client — synchronous and asynchronous."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import httpx
+
+from deutero._http import _DEFAULT_BASE_URL, _DEFAULT_TIMEOUT, AsyncHTTPClient, SyncHTTPClient
+from deutero.resources.analysis import Analysis, AsyncAnalysis
+from deutero.resources.characteristics import AsyncCharacteristics, Characteristics
+from deutero.resources.credits import AsyncCredits, Credits
+from deutero.resources.embed import AsyncEmbed, Embed
+from deutero.resources.graph import AsyncGraph, Graph
+from deutero.resources.interviews import AsyncInterviews, Interviews
+from deutero.resources.personas import AsyncPersonas, Personas
+from deutero.resources.projects import AsyncProjects, Projects
+from deutero.resources.questions import AsyncQuestions, Questions
+from deutero.resources.recruitment import AsyncRecruitment, Recruitment
+from deutero.resources.screening import AsyncScreening, Screening
+from deutero.resources.simulations import AsyncSimulations, Simulations
+from deutero.resources.studies import AsyncStudies, Studies
+from deutero.resources.transcripts import AsyncTranscripts, Transcripts
+from deutero.resources.webhooks import AsyncWebhooks, Webhooks
+from deutero.resources.welcome import AsyncWelcome, Welcome
+
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    resolved_key = api_key or os.environ.get("DEUTERO_API_KEY", "")
+    if not resolved_key:
+        raise ValueError(
+            "No API key provided. Pass api_key= or set the DEUTERO_API_KEY environment variable."
+        )
+    return resolved_key
+
+
+class Deutero:
+    """Synchronous client for the Deutero Study Management API.
+
+    Usage::
+
+        from deutero import Deutero
+
+        client = Deutero(api_key="your-api-key")
+
+        project = client.projects.create(name="Onboarding research")
+        study = client.studies.create(project_id=project.id, name="Why new users drop off")
+
+    The API key can also be set via the ``DEUTERO_API_KEY`` environment variable.
+
+    Args:
+        api_key: Your Deutero API key. Falls back to ``DEUTERO_API_KEY`` env var.
+        base_url: Override the base URL (default: ``https://dashboard.deutero.ai/study-api``).
+        timeout: Request timeout in seconds (default: 120).
+        http_client: Optional pre-configured :class:`httpx.Client`.
+    """
+
+    projects: Projects
+    studies: Studies
+    welcome: Welcome
+    screening: Screening
+    characteristics: Characteristics
+    questions: Questions
+    graph: Graph
+    recruitment: Recruitment
+    embed: Embed
+    personas: Personas
+    simulations: Simulations
+    interviews: Interviews
+    transcripts: Transcripts
+    analysis: Analysis
+    webhooks: Webhooks
+    credits: Credits
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._http = SyncHTTPClient(
+            api_key=_resolve_api_key(api_key),
+            base_url=base_url or _DEFAULT_BASE_URL,
+            timeout=timeout or _DEFAULT_TIMEOUT,
+            http_client=http_client,
+        )
+
+        self.projects = Projects(self._http)
+        self.studies = Studies(self._http)
+        self.welcome = Welcome(self._http)
+        self.screening = Screening(self._http)
+        self.characteristics = Characteristics(self._http)
+        self.questions = Questions(self._http)
+        self.graph = Graph(self._http)
+        self.recruitment = Recruitment(self._http)
+        self.embed = Embed(self._http)
+        self.personas = Personas(self._http)
+        self.simulations = Simulations(self._http)
+        self.interviews = Interviews(self._http)
+        self.transcripts = Transcripts(self._http)
+        self.analysis = Analysis(self._http)
+        self.webhooks = Webhooks(self._http)
+        self.credits = Credits(self._http)
+
+    def health(self) -> Dict[str, Any]:
+        """Liveness check. Does not require a valid API key."""
+        data: Dict[str, Any] = self._http.get("/health")
+        return data
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> Deutero:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Deutero(base_url={self._http._base_url!r})"
+
+
+class AsyncDeutero:
+    """Asynchronous client for the Deutero Study Management API.
+
+    Usage::
+
+        import asyncio
+        from deutero import AsyncDeutero
+
+        async def main():
+            async with AsyncDeutero(api_key="your-api-key") as client:
+                projects = await client.projects.list()
+
+        asyncio.run(main())
+
+    The API key can also be set via the ``DEUTERO_API_KEY`` environment variable.
+
+    Args:
+        api_key: Your Deutero API key. Falls back to ``DEUTERO_API_KEY`` env var.
+        base_url: Override the base URL (default: ``https://dashboard.deutero.ai/study-api``).
+        timeout: Request timeout in seconds (default: 120).
+        http_client: Optional pre-configured :class:`httpx.AsyncClient`.
+    """
+
+    projects: AsyncProjects
+    studies: AsyncStudies
+    welcome: AsyncWelcome
+    screening: AsyncScreening
+    characteristics: AsyncCharacteristics
+    questions: AsyncQuestions
+    graph: AsyncGraph
+    recruitment: AsyncRecruitment
+    embed: AsyncEmbed
+    personas: AsyncPersonas
+    simulations: AsyncSimulations
+    interviews: AsyncInterviews
+    transcripts: AsyncTranscripts
+    analysis: AsyncAnalysis
+    webhooks: AsyncWebhooks
+    credits: AsyncCredits
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._http = AsyncHTTPClient(
+            api_key=_resolve_api_key(api_key),
+            base_url=base_url or _DEFAULT_BASE_URL,
+            timeout=timeout or _DEFAULT_TIMEOUT,
+            http_client=http_client,
+        )
+
+        self.projects = AsyncProjects(self._http)
+        self.studies = AsyncStudies(self._http)
+        self.welcome = AsyncWelcome(self._http)
+        self.screening = AsyncScreening(self._http)
+        self.characteristics = AsyncCharacteristics(self._http)
+        self.questions = AsyncQuestions(self._http)
+        self.graph = AsyncGraph(self._http)
+        self.recruitment = AsyncRecruitment(self._http)
+        self.embed = AsyncEmbed(self._http)
+        self.personas = AsyncPersonas(self._http)
+        self.simulations = AsyncSimulations(self._http)
+        self.interviews = AsyncInterviews(self._http)
+        self.transcripts = AsyncTranscripts(self._http)
+        self.analysis = AsyncAnalysis(self._http)
+        self.webhooks = AsyncWebhooks(self._http)
+        self.credits = AsyncCredits(self._http)
+
+    async def health(self) -> Dict[str, Any]:
+        """Liveness check. See :meth:`Deutero.health`."""
+        data: Dict[str, Any] = await self._http.get("/health")
+        return data
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncDeutero:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncDeutero(base_url={self._http._base_url!r})"