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

struai/models/__init__.py

@@ -0,0 +1,62 @@
+"""StruAI models."""
+from .common import BBox, Dimensions, Point, TextSpan
+from .drawings import (
+    Annotations,
+    DetailTag,
+    DrawingResult,
+    Leader,
+    RevisionCloud,
+    RevisionTriangle,
+    SectionTag,
+    TitleBlock,
+)
+from .entities import Entity, EntityListItem, EntityLocation, EntityRelation, Fact
+from .projects import JobStatus, JobStep, Project, Sheet, SheetResult
+from .search import (
+    EntitySummary,
+    GraphContext,
+    QueryResponse,
+    QuerySource,
+    RelationshipSummary,
+    SearchFilters,
+    SearchHit,
+    SearchResponse,
+)
+
+__all__ = [
+    # Common
+    "Point",
+    "BBox",
+    "TextSpan",
+    "Dimensions",
+    # Drawings (Tier 1)
+    "DrawingResult",
+    "Annotations",
+    "Leader",
+    "SectionTag",
+    "DetailTag",
+    "RevisionTriangle",
+    "RevisionCloud",
+    "TitleBlock",
+    # Projects (Tier 2)
+    "Project",
+    "Sheet",
+    "JobStatus",
+    "JobStep",
+    "SheetResult",
+    # Search
+    "SearchFilters",
+    "SearchHit",
+    "SearchResponse",
+    "EntitySummary",
+    "GraphContext",
+    "RelationshipSummary",
+    "QueryResponse",
+    "QuerySource",
+    # Entities
+    "Entity",
+    "EntityListItem",
+    "EntityLocation",
+    "EntityRelation",
+    "Fact",
+]

struai/models/common.py

@@ -0,0 +1,36 @@
+"""Common types shared across models."""
+from typing import List, Tuple
+
+from pydantic import BaseModel
+
+# Coordinate types
+Point = Tuple[float, float]  # [x, y]
+BBox = Tuple[float, float, float, float]  # [x1, y1, x2, y2]
+
+
+class TextSpan(BaseModel):
+    """Text detected inside an annotation."""
+
+    id: int
+    text: str
+
+
+class Dimensions(BaseModel):
+    """Page dimensions in pixels."""
+
+    width: int
+    height: int
+
+
+class Circle(BaseModel):
+    """Circle geometry."""
+
+    center: Point
+    radius: float
+
+
+class Line(BaseModel):
+    """Line segment."""
+
+    start: Point
+    end: Point

struai/models/drawings.py

@@ -0,0 +1,81 @@
+"""Tier 1: Raw Detection models."""
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+from .common import BBox, Circle, Dimensions, Line, Point, TextSpan
+
+
+class Leader(BaseModel):
+    """Leader annotation with arrow and text."""
+
+    id: str
+    bbox: BBox
+    arrow_tip: Point
+    text_bbox: BBox
+    texts_inside: List[TextSpan]
+
+
+class SectionTag(BaseModel):
+    """Section cut tag."""
+
+    id: str
+    bbox: BBox
+    circle: Circle
+    direction: str  # "left", "right", "up", "down"
+    texts_inside: List[TextSpan]
+    section_line: Optional[Line] = None
+
+
+class DetailTag(BaseModel):
+    """Detail callout tag."""
+
+    id: str
+    bbox: BBox
+    circle: Circle
+    texts_inside: List[TextSpan]
+    has_dashed_bbox: bool = False
+
+
+class RevisionTriangle(BaseModel):
+    """Revision marker triangle."""
+
+    id: str
+    bbox: BBox
+    vertices: List[Point]
+    text: str
+
+
+class RevisionCloud(BaseModel):
+    """Revision cloud boundary."""
+
+    id: str
+    bbox: BBox
+
+
+class Annotations(BaseModel):
+    """All detected annotations."""
+
+    leaders: List[Leader] = []
+    section_tags: List[SectionTag] = []
+    detail_tags: List[DetailTag] = []
+    revision_triangles: List[RevisionTriangle] = []
+    revision_clouds: List[RevisionCloud] = []
+
+
+class TitleBlock(BaseModel):
+    """Title block detection."""
+
+    bounds: BBox
+    viewport: BBox  # Drawing area excluding title block
+
+
+class DrawingResult(BaseModel):
+    """Result from Tier 1 raw detection."""
+
+    id: str
+    page: int
+    dimensions: Dimensions
+    processing_ms: int
+    annotations: Annotations
+    titleblock: Optional[TitleBlock] = None

struai/models/entities.py

@@ -0,0 +1,62 @@
+"""Entity and Relationship models."""
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+from .common import BBox
+
+
+class EntityLocation(BaseModel):
+    """Where an entity appears."""
+
+    sheet_id: str
+    sheet_title: Optional[str] = None
+    page: Optional[int] = None
+
+
+class EntityRelation(BaseModel):
+    """Relationship entry on an entity detail response."""
+
+    uuid: str
+    type: str
+    fact: str
+    source_id: Optional[str] = None
+    source_label: Optional[str] = None
+    target_id: Optional[str] = None
+    target_label: Optional[str] = None
+
+
+class Fact(BaseModel):
+    """Relationship between entities (list endpoint)."""
+
+    id: str
+    type: str
+    fact: str
+    source_id: str
+    target_id: str
+    source_label: Optional[str] = None
+    target_label: Optional[str] = None
+
+
+class EntityListItem(BaseModel):
+    """Entity summary from list endpoint."""
+
+    id: str
+    type: str
+    label: str
+    description: Optional[str] = None
+    sheet_id: Optional[str] = None
+    bbox: Optional[BBox] = None
+    attributes: Optional[str] = None
+
+
+class Entity(BaseModel):
+    """Full entity with relationships."""
+
+    id: str
+    type: str
+    label: str
+    description: Optional[str] = None
+    outgoing: List[EntityRelation] = []
+    incoming: List[EntityRelation] = []
+    locations: List[EntityLocation] = []

struai/models/projects.py

@@ -0,0 +1,83 @@
+"""Tier 2: Project and Sheet models."""
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class Project(BaseModel):
+    """Project container for sheets."""
+
+    id: str
+    name: str
+    description: Optional[str] = None
+    created_at: datetime
+    sheets_count: int = 0
+    entities_count: int = 0
+
+
+class Sheet(BaseModel):
+    """Sheet in a project."""
+
+    id: str
+    title: Optional[str] = None
+    name: Optional[str] = None
+    page: int
+    width: int
+    height: int
+    created_at: datetime
+    entities_count: int = 0
+
+
+class StepStatus(str, Enum):
+    """Status of a pipeline step."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETE = "complete"
+    FAILED = "failed"
+
+
+class JobStep(BaseModel):
+    """Status of a single pipeline step."""
+
+    status: StepStatus
+    duration_ms: Optional[int] = None
+    tokens: Optional[int] = None
+    error: Optional[str] = None
+
+
+class JobSteps(BaseModel):
+    """All pipeline steps."""
+
+    detection: JobStep
+    enrichment: JobStep
+    synthesis: JobStep
+    graph: JobStep
+
+
+class SheetResult(BaseModel):
+    """Result of sheet ingestion."""
+
+    sheet_id: str
+    entities_created: int
+    relationships_created: int
+
+
+class JobStatus(BaseModel):
+    """Current job status."""
+
+    job_id: str
+    status: str  # "processing", "complete", "failed"
+    steps: JobSteps
+    result: Optional[SheetResult] = None
+    error: Optional[str] = None
+
+    @property
+    def is_complete(self) -> bool:
+        return self.status == "complete"
+
+    @property
+    def is_failed(self) -> bool:
+        return self.status == "failed"

struai/models/search.py

@@ -0,0 +1,70 @@
+"""Search and Query models."""
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+from .common import BBox
+
+
+class SearchFilters(BaseModel):
+    """Filters for search."""
+
+    sheet_id: Optional[str] = None
+    entity_type: Optional[List[str]] = None
+
+
+class EntitySummary(BaseModel):
+    """Brief entity info in search results."""
+
+    id: str
+    type: str
+    label: str
+    description: Optional[str] = None
+    sheet_id: str
+    bbox: Optional[BBox] = None
+
+
+class RelationshipSummary(BaseModel):
+    """Brief relationship info."""
+
+    type: str
+    fact: str
+
+
+class GraphContext(BaseModel):
+    """Graph context for a search result."""
+
+    connected_entities: List[EntitySummary]
+    relationships: List[RelationshipSummary]
+
+
+class SearchHit(BaseModel):
+    """Single search result."""
+
+    entity: EntitySummary
+    score: float
+    graph_context: Optional[GraphContext] = None
+
+
+class SearchResponse(BaseModel):
+    """Search response."""
+
+    results: List[SearchHit]
+    search_ms: int
+
+
+class QuerySource(BaseModel):
+    """Source citation for query answer."""
+
+    entity_id: str
+    sheet_id: str
+    label: str
+    bbox: Optional[BBox] = None
+
+
+class QueryResponse(BaseModel):
+    """Natural language query response."""
+
+    answer: str
+    sources: List[QuerySource]
+    confidence: float

struai/resources/__init__.py

@@ -0,0 +1,5 @@
+"""API resources."""
+from .drawings import AsyncDrawings, Drawings
+from .projects import AsyncProjects, Projects
+
+__all__ = ["Drawings", "AsyncDrawings", "Projects", "AsyncProjects"]

struai/resources/drawings.py

@@ -0,0 +1,122 @@
+"""Tier 1: Raw Detection API."""
+from pathlib import Path
+from typing import TYPE_CHECKING, BinaryIO, Union
+
+from ..models.drawings import DrawingResult
+
+if TYPE_CHECKING:
+    from .._base import AsyncBaseClient, BaseClient
+
+
+class Drawings:
+    """Tier 1: Raw detection API (sync)."""
+
+    def __init__(self, client: "BaseClient"):
+        self._client = client
+
+    def analyze(
+        self,
+        file: Union[str, Path, bytes, BinaryIO],
+        page: int,
+    ) -> DrawingResult:
+        """Analyze a PDF page for annotations.
+
+        Args:
+            file: PDF file path, bytes, or file-like object
+            page: Page number (1-indexed)
+
+        Returns:
+            DrawingResult with detected annotations
+
+        Example:
+            >>> result = client.drawings.analyze("structural.pdf", page=4)
+            >>> for leader in result.annotations.leaders:
+            ...     print(leader.texts_inside[0].text)
+        """
+        files = self._prepare_file(file)
+        return self._client.post(
+            "/drawings",
+            files=files,
+            data={"page": str(page)},
+            cast_to=DrawingResult,
+        )
+
+    def get(self, drawing_id: str) -> DrawingResult:
+        """Retrieve a previously processed drawing.
+
+        Args:
+            drawing_id: Drawing ID (e.g., "drw_7f8a9b2c")
+        """
+        return self._client.get(f"/drawings/{drawing_id}", cast_to=DrawingResult)
+
+    def delete(self, drawing_id: str) -> None:
+        """Delete a drawing result.
+
+        Args:
+            drawing_id: Drawing ID to delete
+        """
+        self._client.delete(f"/drawings/{drawing_id}")
+
+    def _prepare_file(self, file: Union[str, Path, bytes, BinaryIO]) -> dict:
+        """Prepare file for upload."""
+        if isinstance(file, (str, Path)):
+            path = Path(file)
+            return {"file": (path.name, open(path, "rb"), "application/pdf")}
+        elif isinstance(file, bytes):
+            return {"file": ("document.pdf", file, "application/pdf")}
+        else:
+            # File-like object
+            name = getattr(file, "name", "document.pdf")
+            if hasattr(name, "split"):
+                name = Path(name).name
+            return {"file": (name, file, "application/pdf")}
+
+
+class AsyncDrawings:
+    """Tier 1: Raw detection API (async)."""
+
+    def __init__(self, client: "AsyncBaseClient"):
+        self._client = client
+
+    async def analyze(
+        self,
+        file: Union[str, Path, bytes, BinaryIO],
+        page: int,
+    ) -> DrawingResult:
+        """Analyze a PDF page for annotations (async).
+
+        Args:
+            file: PDF file path, bytes, or file-like object
+            page: Page number (1-indexed)
+
+        Returns:
+            DrawingResult with detected annotations
+        """
+        files = self._prepare_file(file)
+        return await self._client.post(
+            "/drawings",
+            files=files,
+            data={"page": str(page)},
+            cast_to=DrawingResult,
+        )
+
+    async def get(self, drawing_id: str) -> DrawingResult:
+        """Retrieve a previously processed drawing (async)."""
+        return await self._client.get(f"/drawings/{drawing_id}", cast_to=DrawingResult)
+
+    async def delete(self, drawing_id: str) -> None:
+        """Delete a drawing result (async)."""
+        await self._client.delete(f"/drawings/{drawing_id}")
+
+    def _prepare_file(self, file: Union[str, Path, bytes, BinaryIO]) -> dict:
+        """Prepare file for upload."""
+        if isinstance(file, (str, Path)):
+            path = Path(file)
+            return {"file": (path.name, open(path, "rb"), "application/pdf")}
+        elif isinstance(file, bytes):
+            return {"file": ("document.pdf", file, "application/pdf")}
+        else:
+            name = getattr(file, "name", "document.pdf")
+            if hasattr(name, "split"):
+                name = Path(name).name
+            return {"file": (name, file, "application/pdf")}