struai 0.0.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

struai/__init__.py

@@ -1,2 +1,112 @@
-"""struai"""
-__version__ = "0.0.1"
+"""StruAI Python SDK - Drawing Analysis API client.
+
+Example:
+    >>> from struai import StruAI
+    >>>
+    >>> client = StruAI(api_key="sk-xxx")
+    >>>
+    >>> # Tier 1: Raw detection ($0.02/page)
+    >>> result = client.drawings.analyze("plans.pdf", page=4)
+    >>> for leader in result.annotations.leaders:
+    ...     print(leader.texts_inside[0].text)
+    >>>
+    >>> # Tier 2: Graph + Search ($0.15/page)
+    >>> project = client.projects.create("Building A")
+    >>> job = project.sheets.add("plans.pdf", page=4)
+    >>> job.wait()
+    >>> results = project.search("W12x26 beam connections")
+"""
+
+from ._version import __version__
+from ._client import StruAI, AsyncStruAI
+from ._exceptions import (
+    StruAIError,
+    APIError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    InternalServerError,
+    TimeoutError,
+    ConnectionError,
+    JobFailedError,
+)
+
+# Re-export commonly used models
+from .models import (
+    # Common
+    Point,
+    BBox,
+    TextSpan,
+    Dimensions,
+    # Tier 1 - Drawings
+    DrawingResult,
+    Annotations,
+    Leader,
+    SectionTag,
+    DetailTag,
+    RevisionTriangle,
+    RevisionCloud,
+    TitleBlock,
+    # Tier 2 - Projects
+    Project,
+    Sheet,
+    JobStatus,
+    SheetResult,
+    # Search
+    SearchResponse,
+    SearchHit,
+    QueryResponse,
+    # Entities
+    Entity,
+    EntityListItem,
+    EntityRelation,
+    Fact,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Clients
+    "StruAI",
+    "AsyncStruAI",
+    # Exceptions
+    "StruAIError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "InternalServerError",
+    "TimeoutError",
+    "ConnectionError",
+    "JobFailedError",
+    # Models - Common
+    "Point",
+    "BBox",
+    "TextSpan",
+    "Dimensions",
+    # Models - Tier 1
+    "DrawingResult",
+    "Annotations",
+    "Leader",
+    "SectionTag",
+    "DetailTag",
+    "RevisionTriangle",
+    "RevisionCloud",
+    "TitleBlock",
+    # Models - Tier 2
+    "Project",
+    "Sheet",
+    "JobStatus",
+    "SheetResult",
+    "SearchResponse",
+    "SearchHit",
+    "QueryResponse",
+    "Entity",
+    "EntityListItem",
+    "EntityRelation",
+    "Fact",
+]

struai/_base.py

@@ -0,0 +1,360 @@
+"""Base HTTP client with retry logic."""
+import time
+from typing import Any, Dict, Optional, Type, TypeVar, Union
+from urllib.parse import urlparse
+
+import httpx
+from pydantic import BaseModel
+
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    TimeoutError,
+    ValidationError,
+)
+from ._version import __version__
+
+T = TypeVar("T", bound=BaseModel)
+
+DEFAULT_BASE_URL = "https://api.stru.ai"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+
+
+def _normalize_base_url(base_url: str) -> str:
+    trimmed = base_url.rstrip("/")
+    parsed = urlparse(trimmed)
+    if parsed.scheme and parsed.netloc:
+        path = parsed.path.rstrip("/")
+        if path in ("", "/"):
+            return f"{trimmed}/v1"
+        return trimmed
+    if trimmed.endswith("/v1"):
+        return trimmed
+    return f"{trimmed}/v1"
+
+
+class BaseClient:
+    """Base HTTP client with retry logic."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        self.api_key = api_key
+        self.base_url = _normalize_base_url(base_url)
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client: Optional[httpx.Client] = None
+
+    def _get_client(self) -> httpx.Client:
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                headers=self._default_headers(),
+                timeout=self.timeout,
+            )
+        return self._client
+
+    def _default_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"struai-python/{__version__}",
+            "Accept": "application/json",
+        }
+
+    def _handle_response_error(self, response: httpx.Response) -> None:
+        """Raise appropriate exception for error responses."""
+        if response.status_code < 400:
+            return
+
+        try:
+            body = response.json()
+            error = body.get("error", {})
+            message = error.get("message", response.text)
+            code = error.get("code")
+        except Exception:
+            message = response.text
+            code = None
+
+        request_id = response.headers.get("x-request-id")
+
+        exc_map = {
+            401: AuthenticationError,
+            403: PermissionDeniedError,
+            404: NotFoundError,
+            422: ValidationError,
+            429: RateLimitError,
+        }
+
+        if response.status_code in exc_map:
+            exc_class = exc_map[response.status_code]
+        elif response.status_code >= 500:
+            exc_class = InternalServerError
+        else:
+            exc_class = APIError
+
+        if exc_class == RateLimitError:
+            retry_after = int(response.headers.get("Retry-After", 30))
+            raise RateLimitError(
+                message,
+                status_code=response.status_code,
+                code=code,
+                request_id=request_id,
+                response=response,
+                retry_after=retry_after,
+            )
+
+        raise exc_class(
+            message,
+            status_code=response.status_code,
+            code=code,
+            request_id=request_id,
+            response=response,
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        cast_to: Optional[Type[T]] = None,
+    ) -> Union[T, Dict[str, Any], None]:
+        """Make HTTP request with retry logic."""
+        client = self._get_client()
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                if files:
+                    response = client.request(
+                        method, path, data=data, files=files, params=params
+                    )
+                else:
+                    response = client.request(method, path, json=json, params=params)
+
+                self._handle_response_error(response)
+
+                # Handle empty responses (DELETE)
+                if response.status_code == 204 or not response.content:
+                    return None
+
+                result = response.json()
+                if cast_to is not None:
+                    return cast_to.model_validate(result)
+                return result
+
+            except httpx.TimeoutException as e:
+                last_error = TimeoutError(f"Request timed out: {e}")
+            except httpx.ConnectError as e:
+                last_error = ConnectionError(f"Connection failed: {e}")
+            except (RateLimitError, InternalServerError) as e:
+                last_error = e
+                if attempt < self.max_retries:
+                    wait = getattr(e, "retry_after", 2 ** (attempt + 1))
+                    time.sleep(min(wait, 30))
+                    continue
+                raise
+            except APIError:
+                raise
+
+            if attempt < self.max_retries:
+                time.sleep(2**attempt)
+            else:
+                raise last_error
+
+        raise last_error  # type: ignore
+
+    def get(self, path: str, **kwargs) -> Any:
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs) -> Any:
+        return self._request("POST", path, **kwargs)
+
+    def delete(self, path: str, **kwargs) -> Any:
+        return self._request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+class AsyncBaseClient:
+    """Async base HTTP client with retry logic."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        self.api_key = api_key
+        self.base_url = _normalize_base_url(base_url)
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client: Optional[httpx.AsyncClient] = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=self._default_headers(),
+                timeout=self.timeout,
+            )
+        return self._client
+
+    def _default_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"struai-python/{__version__}",
+            "Accept": "application/json",
+        }
+
+    def _handle_response_error(self, response: httpx.Response) -> None:
+        """Raise appropriate exception for error responses."""
+        if response.status_code < 400:
+            return
+
+        try:
+            body = response.json()
+            error = body.get("error", {})
+            message = error.get("message", response.text)
+            code = error.get("code")
+        except Exception:
+            message = response.text
+            code = None
+
+        request_id = response.headers.get("x-request-id")
+
+        exc_map = {
+            401: AuthenticationError,
+            403: PermissionDeniedError,
+            404: NotFoundError,
+            422: ValidationError,
+            429: RateLimitError,
+        }
+
+        if response.status_code in exc_map:
+            exc_class = exc_map[response.status_code]
+        elif response.status_code >= 500:
+            exc_class = InternalServerError
+        else:
+            exc_class = APIError
+
+        if exc_class == RateLimitError:
+            retry_after = int(response.headers.get("Retry-After", 30))
+            raise RateLimitError(
+                message,
+                status_code=response.status_code,
+                code=code,
+                request_id=request_id,
+                response=response,
+                retry_after=retry_after,
+            )
+
+        raise exc_class(
+            message,
+            status_code=response.status_code,
+            code=code,
+            request_id=request_id,
+            response=response,
+        )
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        cast_to: Optional[Type[T]] = None,
+    ) -> Union[T, Dict[str, Any], None]:
+        """Make async HTTP request with retry logic."""
+        import asyncio
+
+        client = await self._get_client()
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                if files:
+                    response = await client.request(
+                        method, path, data=data, files=files, params=params
+                    )
+                else:
+                    response = await client.request(
+                        method, path, json=json, params=params
+                    )
+
+                self._handle_response_error(response)
+
+                if response.status_code == 204 or not response.content:
+                    return None
+
+                result = response.json()
+                if cast_to is not None:
+                    return cast_to.model_validate(result)
+                return result
+
+            except httpx.TimeoutException as e:
+                last_error = TimeoutError(f"Request timed out: {e}")
+            except httpx.ConnectError as e:
+                last_error = ConnectionError(f"Connection failed: {e}")
+            except (RateLimitError, InternalServerError) as e:
+                last_error = e
+                if attempt < self.max_retries:
+                    wait = getattr(e, "retry_after", 2 ** (attempt + 1))
+                    await asyncio.sleep(min(wait, 30))
+                    continue
+                raise
+            except APIError:
+                raise
+
+            if attempt < self.max_retries:
+                await asyncio.sleep(2**attempt)
+            else:
+                raise last_error
+
+        raise last_error  # type: ignore
+
+    async def get(self, path: str, **kwargs) -> Any:
+        return await self._request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs) -> Any:
+        return await self._request("POST", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs) -> Any:
+        return await self._request("DELETE", path, **kwargs)
+
+    async def close(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()

struai/_client.py

@@ -0,0 +1,112 @@
+"""Main StruAI client classes."""
+import os
+from functools import cached_property
+from typing import Optional
+
+from ._base import AsyncBaseClient, BaseClient, DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+from ._exceptions import StruAIError
+from .resources.drawings import AsyncDrawings, Drawings
+from .resources.projects import AsyncProjects, Projects
+
+
+class StruAI(BaseClient):
+    """StruAI client for drawing analysis API.
+
+    Args:
+        api_key: Your API key. Falls back to STRUAI_API_KEY env var.
+        base_url: API base URL. Defaults to https://api.stru.ai.
+            If no path is provided, /v1 is appended automatically.
+        timeout: Request timeout in seconds. Default 60.
+        max_retries: Max retry attempts for failed requests. Default 2.
+
+    Example:
+        >>> client = StruAI(api_key="sk-xxx")
+        >>>
+        >>> # Tier 1: Raw detection
+        >>> result = client.drawings.analyze("structural.pdf", page=4)
+        >>> print(result.annotations.leaders[0].texts_inside[0].text)
+        'W12x26'
+        >>>
+        >>> # Tier 2: Graph + Search
+        >>> project = client.projects.create("Building A")
+        >>> job = project.sheets.add("structural.pdf", page=4)
+        >>> job.wait()
+        >>> results = project.search("W12x26 beam connections")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+    ):
+        if api_key is None:
+            api_key = os.environ.get("STRUAI_API_KEY")
+        if api_key is None:
+            raise StruAIError(
+                "API key required. Pass api_key or set STRUAI_API_KEY environment variable."
+            )
+
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url or DEFAULT_BASE_URL,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+    @cached_property
+    def drawings(self) -> Drawings:
+        """Tier 1: Raw detection API."""
+        return Drawings(self)
+
+    @cached_property
+    def projects(self) -> Projects:
+        """Tier 2: Graph + Search API."""
+        return Projects(self)
+
+
+class AsyncStruAI(AsyncBaseClient):
+    """Async StruAI client for drawing analysis API.
+
+    Example:
+        >>> async with AsyncStruAI(api_key="sk-xxx") as client:
+        ...     result = await client.drawings.analyze("structural.pdf", page=4)
+        ...
+        ...     project = await client.projects.create("Building A")
+        ...     job = await project.sheets.add("structural.pdf", page=4)
+        ...     await job.wait()
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+    ):
+        if api_key is None:
+            api_key = os.environ.get("STRUAI_API_KEY")
+        if api_key is None:
+            raise StruAIError(
+                "API key required. Pass api_key or set STRUAI_API_KEY environment variable."
+            )
+
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url or DEFAULT_BASE_URL,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+    @cached_property
+    def drawings(self) -> AsyncDrawings:
+        """Tier 1: Raw detection API."""
+        return AsyncDrawings(self)
+
+    @cached_property
+    def projects(self) -> AsyncProjects:
+        """Tier 2: Graph + Search API."""
+        return AsyncProjects(self)

struai/_exceptions.py

@@ -0,0 +1,103 @@
+"""StruAI exceptions."""
+from typing import Optional
+
+import httpx
+
+
+class StruAIError(Exception):
+    """Base exception for all StruAI errors."""
+
+    pass
+
+
+class APIError(StruAIError):
+    """API returned an error response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        response: Optional[httpx.Response] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.response = response
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code:
+            parts.append(f"code={self.code}")
+        if self.status_code:
+            parts.append(f"status={self.status_code}")
+        return " ".join(parts)
+
+
+class AuthenticationError(APIError):
+    """Invalid or missing API key (401)."""
+
+    pass
+
+
+class PermissionDeniedError(APIError):
+    """Insufficient permissions (403)."""
+
+    pass
+
+
+class NotFoundError(APIError):
+    """Resource not found (404)."""
+
+    pass
+
+
+class ValidationError(APIError):
+    """Invalid request parameters (422)."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """Rate limit exceeded (429)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: Optional[int] = None,
+        **kwargs,
+    ):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class InternalServerError(APIError):
+    """Server error (5xx)."""
+
+    pass
+
+
+class TimeoutError(StruAIError):
+    """Request timed out."""
+
+    pass
+
+
+class ConnectionError(StruAIError):
+    """Network connection failed."""
+
+    pass
+
+
+class JobFailedError(StruAIError):
+    """Async job failed."""
+
+    def __init__(self, message: str, *, job_id: str, error: str):
+        super().__init__(message)
+        self.job_id = job_id
+        self.error = error

struai/_version.py

@@ -0,0 +1,2 @@
+"""Version information."""
+__version__ = "0.2.0"