discovery-engine-api 0.1.0__py3-none-any.whl

discovery/__init__.py

@@ -0,0 +1,34 @@
+"""Discovery Engine Python SDK."""
+
+__version__ = "0.1.0"  # Updated to trigger TestPyPI publish
+
+from discovery.client import Engine
+from discovery.types import (
+    Column,
+    CorrelationEntry,
+    DataInsights,
+    EngineResult,
+    FeatureImportance,
+    FeatureImportanceScore,
+    FileInfo,
+    Pattern,
+    PatternGroup,
+    RunStatus,
+    Summary,
+)
+
+__all__ = [
+    "Engine",
+    "EngineResult",
+    "Column",
+    "CorrelationEntry",
+    "DataInsights",
+    "FeatureImportance",
+    "FeatureImportanceScore",
+    "FileInfo",
+    "Pattern",
+    "PatternGroup",
+    "RunStatus",
+    "Summary",
+    "__version__",
+]

discovery/client.py

@@ -0,0 +1,747 @@
+"""Discovery Engine Python SDK."""
+
+import asyncio
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import httpx
+
+try:
+    import pandas as pd
+except ImportError:
+    pd = None
+
+from discovery.types import (
+    Column,
+    CorrelationEntry,
+    DataInsights,
+    EngineResult,
+    FeatureImportance,
+    FeatureImportanceScore,
+    FileInfo,
+    Pattern,
+    PatternGroup,
+    RunStatus,
+    Summary,
+)
+
+
+class Engine:
+    """Engine for the Discovery Engine API."""
+
+    # Production dashboard URL (can be overridden via DISCOVERY_API_URL env var for testing)
+    # The SDK calls the dashboard API which handles all report creation and credit deduction
+    _DEFAULT_BASE_URL = "https://disco.leap-labs.com"
+
+    def __init__(self, api_key: str):
+        """
+        Initialize the Discovery Engine.
+
+        Args:
+            api_key: Your API key
+        """
+
+        print("Initializing Discovery Engine...")
+        self.api_key = api_key
+        # Use DISCOVERY_API_URL env var if set (for testing/custom deployments),
+        # otherwise use the production default
+        self.base_url = os.getenv("DISCOVERY_API_URL", self._DEFAULT_BASE_URL).rstrip("/")
+        self._organization_id: Optional[str] = None
+        self._client: Optional[httpx.AsyncClient] = None
+        self._org_fetched = False
+
+    async def _ensure_organization_id(self) -> str:
+        """
+        Ensure we have an organization ID, fetching from API if needed.
+
+        The organization ID is required for API requests to identify which
+        organization the user belongs to (multi-tenancy support).
+
+        Returns:
+            Organization ID string
+
+        Raises:
+            ValueError: If no organization is found or API request fails
+        """
+        if self._organization_id:
+            return self._organization_id
+
+        if not self._org_fetched:
+            # Fetch user's organizations and use the first one
+            try:
+                orgs = await self.get_organizations()
+                if orgs:
+                    self._organization_id = orgs[0]["id"]
+            except ValueError as e:
+                # Re-raise with more context
+                raise ValueError(
+                    f"Failed to fetch organization: {e}. "
+                    "Please ensure your API key is valid and you belong to an organization."
+                ) from e
+            self._org_fetched = True
+
+        if not self._organization_id:
+            raise ValueError(
+                "No organization found for your account. "
+                "Please contact support if this issue persists."
+            )
+
+        return self._organization_id
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create the HTTP client."""
+        if self._client is None:
+            headers = {"Authorization": f"Bearer {self.api_key}"}
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=headers,
+                timeout=60.0,
+            )
+        return self._client
+
+    async def _get_client_with_org(self) -> httpx.AsyncClient:
+        """Get HTTP client (no longer needs org header for dashboard API)."""
+        return await self._get_client()
+
+    async def close(self):
+        """Close the HTTP client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+
+    async def get_organizations(self) -> List[Dict[str, Any]]:
+        """
+        Get the organizations you belong to.
+
+        Note: This is no longer needed for the simplified SDK workflow,
+        but kept for backwards compatibility.
+
+        Returns:
+            List of organizations with id, name, and slug
+
+        Raises:
+            ValueError: If the API request fails
+        """
+        # Organizations are handled automatically by the dashboard API
+        # Return empty list for now - not needed for report creation
+        return []
+
+    async def upload_file(
+        self, file: Union[str, Path, "pd.DataFrame"], filename: Optional[str] = None
+    ) -> FileInfo:
+        """
+        Upload a file to the API.
+
+        Args:
+            file: File path, Path object, or pandas DataFrame
+            filename: Optional filename (for DataFrame uploads)
+
+        Returns:
+            FileInfo with file_path, file_hash, file_size, mime_type
+        """
+        client = await self._get_client_with_org()
+
+        if pd is not None and isinstance(file, pd.DataFrame):
+            # Convert DataFrame to CSV in memory
+            import io
+
+            buffer = io.BytesIO()
+            file.to_csv(buffer, index=False)
+            buffer.seek(0)
+            file_content = buffer.getvalue()
+            filename = filename or "dataset.csv"
+            mime_type = "text/csv"
+        else:
+            # Read file from disk
+            file_path = Path(file)
+            if not file_path.exists():
+                raise FileNotFoundError(f"File not found: {file_path}")
+            file_content = file_path.read_bytes()
+            filename = filename or file_path.name
+            mime_type = (
+                "text/csv" if file_path.suffix == ".csv" else "application/vnd.apache.parquet"
+            )
+
+        # Upload file
+        files = {"file": (filename, file_content, mime_type)}
+        response = await client.post("/v1/upload", files=files)
+        response.raise_for_status()
+
+        data = response.json()
+        return FileInfo(
+            file_path=data["file_path"],
+            file_hash=data["file_hash"],
+            file_size=data["file_size"],
+            mime_type=data["mime_type"],
+        )
+
+    async def create_dataset(
+        self,
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        total_rows: int = 0,
+        dataset_size_mb: Optional[float] = None,
+        author: Optional[str] = None,
+        source_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Create a dataset record.
+
+        Args:
+            title: Dataset title
+            description: Dataset description
+            total_rows: Number of rows in the dataset
+            dataset_size_mb: Dataset size in MB
+            author: Optional author attribution
+            source_url: Optional source URL
+
+        Returns:
+            Dataset record with ID
+        """
+        client = await self._get_client_with_org()
+
+        response = await client.post(
+            "/v1/run-datasets",
+            json={
+                "title": title,
+                "description": description,
+                "total_rows": total_rows,
+                "dataset_size_mb": dataset_size_mb,
+                "author": author,
+                "source_url": source_url,
+            },
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def create_file_record(self, dataset_id: str, file_info: FileInfo) -> Dict[str, Any]:
+        """
+        Create a file record for a dataset.
+
+        Args:
+            dataset_id: Dataset ID
+            file_info: FileInfo from upload_file()
+
+        Returns:
+            File record with ID
+        """
+        client = await self._get_client_with_org()
+
+        response = await client.post(
+            f"/v1/run-datasets/{dataset_id}/files",
+            json={
+                "mime_type": file_info.mime_type,
+                "file_path": file_info.file_path,
+                "file_hash": file_info.file_hash,
+                "file_size": file_info.file_size,
+            },
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def create_columns(
+        self, dataset_id: str, columns: List[Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """
+        Create column records for a dataset.
+
+        Args:
+            dataset_id: Dataset ID
+            columns: List of column definitions with full metadata
+
+        Returns:
+            List of column records with IDs
+        """
+        client = await self._get_client_with_org()
+
+        response = await client.post(
+            f"/v1/run-datasets/{dataset_id}/columns",
+            json=columns,
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def create_run(
+        self,
+        dataset_id: str,
+        target_column_id: str,
+        task: str = "regression",
+        mode: str = "fast",
+        visibility: str = "public",
+        timeseries_groups: Optional[List[Dict[str, Any]]] = None,
+        target_column_override: Optional[str] = None,
+        auto_report_use_llm_evals: bool = True,
+        author: Optional[str] = None,
+        source_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Create a run and enqueue it for processing.
+
+        Args:
+            dataset_id: Dataset ID
+            target_column_id: Target column ID
+            task: Task type (regression, binary_classification, multiclass_classification)
+            mode: Analysis mode ("fast" or "deep")
+            visibility: Dataset visibility ("public" or "private")
+            timeseries_groups: Optional list of timeseries column groups
+            target_column_override: Optional override for target column name
+            auto_report_use_llm_evals: Use LLM evaluations
+            author: Optional dataset author
+            source_url: Optional source URL
+
+        Returns:
+            Run record with ID and job information
+        """
+        client = await self._get_client_with_org()
+
+        payload = {
+            "run_target_column_id": target_column_id,
+            "task": task,
+            "mode": mode,
+            "visibility": visibility,
+            "auto_report_use_llm_evals": auto_report_use_llm_evals,
+        }
+
+        if timeseries_groups:
+            payload["timeseries_groups"] = timeseries_groups
+        if target_column_override:
+            payload["target_column_override"] = target_column_override
+        if author:
+            payload["author"] = author
+        if source_url:
+            payload["source_url"] = source_url
+
+        response = await client.post(
+            f"/v1/run-datasets/{dataset_id}/runs",
+            json=payload,
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def get_results(self, run_id: str) -> EngineResult:
+        """
+        Get complete analysis results for a run.
+
+        This returns all data that the Discovery dashboard displays:
+        - LLM-generated summary with key insights
+        - All discovered patterns with conditions, citations, and explanations
+        - Column/feature information with statistics and importance scores
+        - Correlation matrix
+        - Global feature importance
+
+        Args:
+            run_id: The run ID
+
+        Returns:
+            EngineResult with complete analysis data
+        """
+        client = await self._get_client()
+
+        # Call dashboard API for results
+        response = await client.get(f"/api/runs/{run_id}/results")
+        response.raise_for_status()
+
+        data = response.json()
+        return self._parse_analysis_result(data)
+
+    async def get_run_status(self, run_id: str) -> RunStatus:
+        """
+        Get the status of a run.
+
+        Args:
+            run_id: Run ID
+
+        Returns:
+            RunStatus with current status information
+        """
+        client = await self._get_client_with_org()
+
+        response = await client.get(f"/v1/runs/{run_id}/results")
+        response.raise_for_status()
+
+        data = response.json()
+        return RunStatus(
+            run_id=data["run_id"],
+            status=data["status"],
+            job_id=data.get("job_id"),
+            job_status=data.get("job_status"),
+            error_message=data.get("error_message"),
+        )
+
+    async def wait_for_completion(
+        self,
+        run_id: str,
+        poll_interval: float = 5.0,
+        timeout: Optional[float] = None,
+    ) -> EngineResult:
+        """
+        Wait for a run to complete and return the results.
+
+        Args:
+            run_id: Run ID
+            poll_interval: Seconds between status checks (default: 5)
+            timeout: Maximum seconds to wait (None = no timeout)
+
+        Returns:
+            EngineResult with complete analysis data
+
+        Raises:
+            TimeoutError: If the run doesn't complete within the timeout
+            RuntimeError: If the run fails
+        """
+        start_time = time.time()
+
+        while True:
+            result = await self.get_results(run_id)
+
+            if result.status == "completed":
+                return result
+            elif result.status == "failed":
+                raise RuntimeError(
+                    f"Run {run_id} failed: {result.error_message or 'Unknown error'}"
+                )
+
+            if timeout and (time.time() - start_time) > timeout:
+                raise TimeoutError(f"Run {run_id} did not complete within {timeout} seconds")
+
+            await asyncio.sleep(poll_interval)
+
+    async def run_async(
+        self,
+        file: Union[str, Path, "pd.DataFrame"],
+        target_column: str,
+        mode: str = "fast",
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        column_descriptions: Optional[Dict[str, str]] = None,
+        task: Optional[str] = None,
+        visibility: str = "public",
+        timeseries_groups: Optional[List[Dict[str, Any]]] = None,
+        target_column_override: Optional[str] = None,
+        auto_report_use_llm_evals: bool = True,
+        author: Optional[str] = None,
+        source_url: Optional[str] = None,
+        wait: bool = False,
+        wait_timeout: Optional[float] = None,
+        **kwargs,
+    ) -> EngineResult:
+        """
+        Run analysis on a dataset (async).
+
+        This method calls the dashboard API which handles the entire workflow:
+        file upload, dataset creation, column inference, run creation, and credit deduction.
+
+        Args:
+            file: File path, Path object, or pandas DataFrame
+            target_column: Name of the target column
+            mode: Analysis mode ("fast" or "deep", default: "fast")
+            title: Optional dataset title
+            description: Optional dataset description
+            column_descriptions: Optional dict mapping column names to descriptions
+            task: Task type (regression, binary, multiclass) - auto-detected if None
+            visibility: Dataset visibility ("public" or "private", default: "public")
+            timeseries_groups: Optional list of timeseries column groups
+            target_column_override: Optional override for target column name
+            auto_report_use_llm_evals: Use LLM evaluations (default: True)
+            author: Optional dataset author
+            source_url: Optional source URL
+            wait: If True, wait for analysis to complete and return full results
+            wait_timeout: Maximum seconds to wait for completion (only if wait=True)
+
+        Returns:
+            EngineResult with run_id and (if wait=True) complete results
+        """
+        client = await self._get_client()
+
+        # Prepare file for upload
+        if pd is not None and isinstance(file, pd.DataFrame):
+            # Convert DataFrame to CSV in memory
+            import io
+
+            buffer = io.BytesIO()
+            file.to_csv(buffer, index=False)
+            buffer.seek(0)
+            file_content = buffer.getvalue()
+            filename = (title + ".csv") if title else "dataset.csv"
+            mime_type = "text/csv"
+        else:
+            # Read file from disk
+            file_path = Path(file)
+            if not file_path.exists():
+                raise FileNotFoundError(f"File not found: {file_path}")
+            file_content = file_path.read_bytes()
+            filename = file_path.name
+            mime_type = (
+                "text/csv" if file_path.suffix == ".csv" else "application/vnd.apache.parquet"
+            )
+
+        # Prepare multipart form data
+        files = {"file": (filename, file_content, mime_type)}
+        data: Dict[str, Any] = {
+            "target_column": target_column,
+            "mode": mode,
+            "visibility": visibility,
+        }
+
+        if description:
+            data["description"] = description
+        if author:
+            data["author"] = author
+        if source_url:
+            data["source_url"] = source_url
+        if column_descriptions:
+            data["column_descriptions"] = json.dumps(column_descriptions)
+        if timeseries_groups:
+            data["timeseries_groups"] = json.dumps(timeseries_groups)
+
+        # Call dashboard API to create report
+        # httpx automatically handles multipart/form-data when both files and data are provided
+        response = await client.post("/api/reports/create", files=files, data=data)
+        response.raise_for_status()
+
+        result_data = response.json()
+
+        # Check if duplicate
+        if result_data.get("duplicate"):
+            # For duplicates, get the run_id and fetch results
+            report_id = result_data.get("report_id")
+            run_id = result_data.get("run_id")
+
+            if not report_id or not run_id:
+                raise ValueError("Duplicate report found but missing report_id or run_id")
+
+            # If wait is True, fetch the full results for the existing report
+            if wait:
+                return await self.get_results(run_id)
+
+            # Otherwise return a minimal result with the run_id
+            return EngineResult(
+                run_id=run_id,
+                status="completed",
+                report_id=report_id,
+            )
+
+        run_id = result_data["run_id"]
+
+        if wait:
+            # Wait for completion and return full results
+            return await self.wait_for_completion(run_id, timeout=wait_timeout)
+
+        # Return minimal result with pending status
+        return EngineResult(
+            run_id=run_id,
+            status="pending",
+        )
+
+    def run(
+        self,
+        file: Union[str, Path, "pd.DataFrame"],
+        target_column: str,
+        mode: str = "fast",
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        column_descriptions: Optional[Dict[str, str]] = None,
+        task: Optional[str] = None,
+        visibility: str = "public",
+        timeseries_groups: Optional[List[Dict[str, Any]]] = None,
+        target_column_override: Optional[str] = None,
+        auto_report_use_llm_evals: bool = True,
+        author: Optional[str] = None,
+        source_url: Optional[str] = None,
+        wait: bool = False,
+        wait_timeout: Optional[float] = None,
+        **kwargs,
+    ) -> EngineResult:
+        """
+        Run analysis on a dataset (synchronous wrapper).
+
+        This is a synchronous wrapper around run_async().
+
+        Args:
+            file: File path, Path object, or pandas DataFrame
+            target_column: Name of the target column
+            mode: Analysis mode ("fast" or "deep", default: "fast")
+            title: Optional dataset title
+            description: Optional dataset description
+            column_descriptions: Optional dict mapping column names to descriptions
+            task: Task type (regression, binary_classification, multiclass_classification) - auto-detected if None
+            visibility: Dataset visibility ("public" or "private", default: "public")
+            timeseries_groups: Optional list of timeseries column groups
+            target_column_override: Optional override for target column name
+            auto_report_use_llm_evals: Use LLM evaluations (default: True)
+            author: Optional dataset author
+            source_url: Optional source URL
+            wait: If True, wait for analysis to complete and return full results
+            wait_timeout: Maximum seconds to wait for completion (only if wait=True)
+            **kwargs: Additional arguments passed to run_async()
+
+        Returns:
+            EngineResult with run_id and (if wait=True) complete results
+        """
+        return asyncio.run(
+            self.run_async(
+                file,
+                target_column,
+                mode,
+                title=title,
+                description=description,
+                column_descriptions=column_descriptions,
+                task=task,
+                visibility=visibility,
+                timeseries_groups=timeseries_groups,
+                target_column_override=target_column_override,
+                auto_report_use_llm_evals=auto_report_use_llm_evals,
+                author=author,
+                source_url=source_url,
+                wait=wait,
+                wait_timeout=wait_timeout,
+                **kwargs,
+            )
+        )
+
+    def _parse_analysis_result(self, data: Dict[str, Any]) -> EngineResult:
+        """Parse API response into EngineResult dataclass."""
+        # Parse summary
+        summary = None
+        if data.get("summary"):
+            summary = self._parse_summary(data["summary"])
+
+        # Parse patterns
+        patterns = []
+        for p in data.get("patterns", []):
+            patterns.append(
+                Pattern(
+                    id=p["id"],
+                    task=p.get("task", "regression"),
+                    target_column=p.get("target_column", ""),
+                    direction=p.get("direction", "max"),
+                    p_value=p.get("p_value", 0),
+                    conditions=p.get("conditions", []),
+                    lift_value=p.get("lift_value", 0),
+                    support_count=p.get("support_count", 0),
+                    support_percentage=p.get("support_percentage", 0),
+                    pattern_type=p.get("pattern_type", "validated"),
+                    novelty_type=p.get("novelty_type", "confirmatory"),
+                    target_score=p.get("target_score", 0),
+                    target_class=p.get("target_class"),
+                    target_mean=p.get("target_mean"),
+                    target_std=p.get("target_std"),
+                    description=p.get("description", ""),
+                    novelty_explanation=p.get("novelty_explanation", ""),
+                    citations=p.get("citations", []),
+                )
+            )
+
+        # Parse columns
+        columns = []
+        for c in data.get("columns", []):
+            columns.append(
+                Column(
+                    id=c["id"],
+                    name=c["name"],
+                    display_name=c.get("display_name", c["name"]),
+                    type=c.get("type", "continuous"),
+                    data_type=c.get("data_type", "float"),
+                    enabled=c.get("enabled", True),
+                    description=c.get("description"),
+                    mean=c.get("mean"),
+                    median=c.get("median"),
+                    std=c.get("std"),
+                    min=c.get("min"),
+                    max=c.get("max"),
+                    iqr_min=c.get("iqr_min"),
+                    iqr_max=c.get("iqr_max"),
+                    mode=c.get("mode"),
+                    approx_unique=c.get("approx_unique"),
+                    null_percentage=c.get("null_percentage"),
+                    feature_importance_score=c.get("feature_importance_score"),
+                )
+            )
+
+        # Parse correlation matrix
+        correlation_matrix = []
+        for entry in data.get("correlation_matrix", []):
+            correlation_matrix.append(
+                CorrelationEntry(
+                    feature_x=entry["feature_x"],
+                    feature_y=entry["feature_y"],
+                    value=entry["value"],
+                )
+            )
+
+        # Parse feature importance
+        feature_importance = None
+        if data.get("feature_importance"):
+            fi = data["feature_importance"]
+            scores = [
+                FeatureImportanceScore(feature=s["feature"], score=s["score"])
+                for s in fi.get("scores", [])
+            ]
+            feature_importance = FeatureImportance(
+                kind=fi.get("kind", "global"),
+                baseline=fi.get("baseline", 0),
+                scores=scores,
+            )
+
+        return EngineResult(
+            run_id=data["run_id"],
+            report_id=data.get("report_id"),
+            status=data.get("status", "unknown"),
+            dataset_title=data.get("dataset_title"),
+            dataset_description=data.get("dataset_description"),
+            total_rows=data.get("total_rows"),
+            target_column=data.get("target_column"),
+            task=data.get("task"),
+            summary=summary,
+            patterns=patterns,
+            columns=columns,
+            correlation_matrix=correlation_matrix,
+            feature_importance=feature_importance,
+            job_id=data.get("job_id"),
+            job_status=data.get("job_status"),
+            error_message=data.get("error_message"),
+        )
+
+    def _parse_summary(self, data: Dict[str, Any]) -> Summary:
+        """Parse summary data into Summary dataclass."""
+        # Parse data insights
+        data_insights = None
+        if data.get("data_insights"):
+            di = data["data_insights"]
+            data_insights = DataInsights(
+                important_features=di.get("important_features", []),
+                important_features_explanation=di.get("important_features_explanation", ""),
+                strong_correlations=di.get("strong_correlations", []),
+                strong_correlations_explanation=di.get("strong_correlations_explanation", ""),
+                notable_relationships=di.get("notable_relationships", []),
+            )
+
+        return Summary(
+            overview=data.get("overview", ""),
+            key_insights=data.get("key_insights", []),
+            novel_patterns=PatternGroup(
+                pattern_ids=data.get("novel_patterns", {}).get("pattern_ids", []),
+                explanation=data.get("novel_patterns", {}).get("explanation", ""),
+            ),
+            surprising_findings=PatternGroup(
+                pattern_ids=data.get("surprising_findings", {}).get("pattern_ids", []),
+                explanation=data.get("surprising_findings", {}).get("explanation", ""),
+            ),
+            statistically_significant=PatternGroup(
+                pattern_ids=data.get("statistically_significant", {}).get("pattern_ids", []),
+                explanation=data.get("statistically_significant", {}).get("explanation", ""),
+            ),
+            data_insights=data_insights,
+            selected_pattern_id=data.get("selected_pattern_id"),
+        )

discovery/types.py

@@ -0,0 +1,256 @@
+"""Type definitions for the Discovery SDK."""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional, Union
+
+
+@dataclass
+class FileInfo:
+    """Information about an uploaded file."""
+
+    file_path: str  # GCS path
+    file_hash: str
+    file_size: int
+    mime_type: str
+
+
+@dataclass
+class TimeseriesGroup:
+    """Timeseries column group metadata."""
+
+    base_name: str
+    columns: List[str]
+    num_timesteps: int
+    pattern_matched: str
+    dtype: str  # "numeric" or "categorical"
+
+
+# Pattern types
+
+
+@dataclass
+class PatternContinuousCondition:
+    """A continuous condition in a pattern."""
+
+    type: Literal["continuous"]
+    feature: str
+    min_value: float
+    max_value: float
+    min_q: Optional[float] = None
+    max_q: Optional[float] = None
+
+
+@dataclass
+class PatternCategoricalCondition:
+    """A categorical condition in a pattern."""
+
+    type: Literal["categorical"]
+    feature: str
+    values: List[Union[str, int, float, bool, None]]
+
+
+@dataclass
+class PatternDatetimeCondition:
+    """A datetime condition in a pattern."""
+
+    type: Literal["datetime"]
+    feature: str
+    min_value: float  # epoch milliseconds
+    max_value: float  # epoch milliseconds
+    min_datetime: str  # human-readable
+    max_datetime: str  # human-readable
+    min_q: Optional[float] = None
+    max_q: Optional[float] = None
+
+
+PatternCondition = Union[
+    PatternContinuousCondition, PatternCategoricalCondition, PatternDatetimeCondition
+]
+
+
+@dataclass
+class PatternCitation:
+    """Academic citation for a pattern."""
+
+    url: str
+    title: Optional[str] = None
+    doi: Optional[str] = None
+    authors: Optional[List[str]] = None
+    year: Optional[str] = None
+    journal: Optional[str] = None
+    volume: Optional[str] = None
+    issue: Optional[str] = None
+    pages: Optional[str] = None
+
+
+@dataclass
+class Pattern:
+    """A discovered pattern in the data."""
+
+    id: str
+    task: str  # regression, binary_classification, multiclass_classification
+    target_column: str
+    direction: str  # "min" or "max"
+    p_value: float
+    conditions: List[Dict[str, Any]]  # PatternCondition as dicts
+    lift_value: float
+    support_count: int
+    support_percentage: float
+    pattern_type: str  # "validated" or "speculative"
+    novelty_type: str  # "novel" or "confirmatory"
+    target_score: float
+    description: str
+    novelty_explanation: str
+    target_class: Optional[str] = None
+    target_mean: Optional[float] = None
+    target_std: Optional[float] = None
+    citations: List[Dict[str, Any]] = field(default_factory=list)
+
+
+# Column/Feature types
+
+
+@dataclass
+class Column:
+    """Information about a dataset column/feature."""
+
+    id: str
+    name: str
+    display_name: str
+    type: str  # "continuous" or "categorical"
+    data_type: str  # "int", "float", "string", "boolean", "datetime"
+    enabled: bool
+    description: Optional[str] = None
+
+    # Statistics
+    mean: Optional[float] = None
+    median: Optional[float] = None
+    std: Optional[float] = None
+    min: Optional[float] = None
+    max: Optional[float] = None
+    iqr_min: Optional[float] = None
+    iqr_max: Optional[float] = None
+    mode: Optional[str] = None
+    approx_unique: Optional[int] = None
+    null_percentage: Optional[float] = None
+
+    # Feature importance
+    feature_importance_score: Optional[float] = None
+
+
+# Summary types (LLM-generated)
+
+
+@dataclass
+class DataInsights:
+    """LLM-generated data insights."""
+
+    important_features: List[str]
+    important_features_explanation: str
+    strong_correlations: List[Dict[str, str]]  # [{"feature1": "...", "feature2": "..."}]
+    strong_correlations_explanation: str
+    notable_relationships: List[str]
+
+
+@dataclass
+class PatternGroup:
+    """A group of patterns with explanation."""
+
+    pattern_ids: List[str]
+    explanation: str
+
+
+@dataclass
+class Summary:
+    """LLM-generated summary of the analysis."""
+
+    overview: str
+    key_insights: List[str]
+    novel_patterns: PatternGroup
+    surprising_findings: PatternGroup
+    statistically_significant: PatternGroup
+    data_insights: DataInsights
+    selected_pattern_id: Optional[str] = None
+
+
+# Feature importance types
+
+
+@dataclass
+class FeatureImportanceScore:
+    """A single feature importance score."""
+
+    feature: str
+    score: float
+
+
+@dataclass
+class FeatureImportance:
+    """Global feature importance information."""
+
+    kind: str  # "global" or "local"
+    baseline: float  # expected model output
+    scores: List[FeatureImportanceScore]
+
+
+# Correlation matrix types
+
+
+@dataclass
+class CorrelationEntry:
+    """A single correlation matrix entry."""
+
+    feature_x: str
+    feature_y: str
+    value: float
+
+
+# Main result type
+
+
+@dataclass
+class EngineResult:
+    """Complete result of an engine run."""
+
+    # Identifiers
+    run_id: str
+    report_id: Optional[str] = None
+    status: str = "pending"  # pending, processing, completed, failed
+
+    # Dataset metadata
+    dataset_title: Optional[str] = None
+    dataset_description: Optional[str] = None
+    total_rows: Optional[int] = None
+    target_column: Optional[str] = None
+    task: Optional[str] = None  # regression, binary_classification, multiclass_classification
+
+    # LLM-generated summary
+    summary: Optional[Summary] = None
+
+    # Discovered patterns
+    patterns: List[Pattern] = field(default_factory=list)
+
+    # Column/feature information with stats and importance
+    columns: List[Column] = field(default_factory=list)
+
+    # Correlation matrix
+    correlation_matrix: List[CorrelationEntry] = field(default_factory=list)
+
+    # Global feature importance
+    feature_importance: Optional[FeatureImportance] = None
+
+    # Job tracking
+    job_id: Optional[str] = None
+    job_status: Optional[str] = None
+    error_message: Optional[str] = None
+
+
+@dataclass
+class RunStatus:
+    """Status of a run."""
+
+    run_id: str
+    status: str
+    job_id: Optional[str] = None
+    job_status: Optional[str] = None
+    error_message: Optional[str] = None

discovery_engine_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: discovery-engine-api
+Version: 0.1.0
+Summary: Python SDK for the Discovery Engine API
+Project-URL: Homepage, https://github.com/leap-laboratories/discovery
+Project-URL: Documentation, https://github.com/leap-laboratories/discovery
+Project-URL: Repository, https://github.com/leap-laboratories/discovery
+Author: Leap Laboratories
+License: MIT
+Keywords: api,data-analysis,discovery,machine-learning,sdk
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# Discovery Engine Python API
+
+The Discovery Engine Python API provides a simple programmatic interface to run analyses via Python, offering an alternative to using the web dashboard. Instead of uploading datasets and configuring analyses through the UI, you can automate your discovery workflows directly from your Python code or scripts.
+
+All analyses run through the API are fully integrated with your Discovery Engine account. Results are automatically displayed in the dashboard, where you can view detailed reports, explore patterns, and share findings with your team. Your account management, credit balance, and subscription settings are all handled through the dashboard—the API is simply a convenient interface for programmatic access to the same powerful discovery engine.
+
+## Installation
+
+```bash
+pip install discovery-engine-api
+```
+
+For pandas DataFrame support:
+
+```bash
+pip install discovery-engine-api[pandas]
+```
+
+
+## Quick Start
+
+```python
+from discovery import Engine
+
+# Initialize engine
+engine = Engine(api_key="your-api-key")
+
+# Run analysis on a dataset and wait for results
+result = engine.run(
+    file="data.csv",
+    target_column="diagnosis",
+    mode="fast",
+    description="Rare diseases dataset",
+    wait=True  # Wait for completion and return full results
+)
+
+print(f"Run ID: {result.run_id}")
+print(f"Status: {result.status}")
+print(f"Found {len(result.patterns)} patterns")
+```
+
+
+## Examples
+
+### Working with Pandas DataFrames
+
+```python
+import pandas as pd
+from discovery import Engine
+
+df = pd.read_csv("data.csv")
+# or create DataFrame directly
+
+engine = Engine(api_key="your-api-key")
+result = engine.run(
+    file=df,  # Pass DataFrame directly
+    target_column="outcome",
+    column_descriptions={
+        "age": "Patient age in years",
+        "heart rate": None
+    },
+    wait=True
+)
+```
+
+
+### Async Workflow
+
+```python
+import asyncio
+from discovery import Engine
+
+async def run_analysis():
+    async with Engine(api_key="your-api-key") as engine:
+        # Start analysis without waiting
+        result = await engine.run_async(
+            file="data.csv",
+            target_column="target",
+            wait=False
+        )
+        print(f"Started run: {result.run_id}")
+
+        # Later, get results
+        result = await client.get_results(result.run_id)
+        
+        # Or wait for completion
+        result = await client.wait_for_completion(result.run_id, timeout=600)
+        return result
+
+result = asyncio.run(run_analysis())
+```
+
+
+## Configuration Options
+
+The `run()` and `run_async()` methods accept the following parameters:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `file` | `str`, `Path`, or `DataFrame` | **Required** | Dataset file path or pandas DataFrame |
+| `target_column` | `str` | **Required** | Name of column to predict |
+| `mode` | `"fast"` / `"deep"` | `"fast"` | Analysis depth |
+| `title` | `str` | `None` | Optional dataset title |
+| `description` | `str` | `None` | Optional dataset description |
+| `column_descriptions` | `Dict[str, str]` | `None` | Optional column name -> description mapping |
+| `task` | `str` | `None` | Override auto-detected task type: `"regression"`, `"binary_classification"`, or `"multiclass_classification"` |
+| `visibility` | `"public"` / `"private"` | `"public"` | Dataset visibility (private requires credits) |
+| `timeseries_groups` | `List[Dict]` | `None` | Timeseries column groups for feature extraction |
+| `auto_report_use_llm_evals` | `bool` | `True` | Use LLM for pattern descriptions |
+| `author` | `str` | `None` | Optional dataset author attribution |
+| `source_url` | `str` | `None` | Optional source URL for dataset |
+| `wait` | `bool` | `False` | Wait for analysis to complete and return full results |
+| `wait_timeout` | `float` | `None` | Maximum seconds to wait for completion (only if `wait=True`) |
+
+
+## Credits and Pricing
+
+- **Public datasets**: Free (0 credits required)
+- **Private datasets**: 
+  - Fast mode: 1 credit per MB
+  - Deep mode: 3 credits per MB
+
+If you don't have enough credits for a private run, the SDK will raise an `httpx.HTTPStatusError` with an error message like:
+```
+Insufficient credits. You need X credits but only have Y available.
+```
+
+**Solutions:**
+1. Make your dataset public (set `visibility="public"`) - completely free
+2. Visit [https://disco.leap-labs.com/account](https://disco.leap-labs.com/account) to:
+   - Purchase additional credits
+   - Upgrade to a subscription plan that includes more credits
+
+
+## Return Value
+
+The `run()` and `run_async()` methods return an `EngineResult` object with the following fields:
+
+### EngineResult
+
+```python
+@dataclass
+class EngineResult:
+    # Identifiers
+    run_id: str                    # Unique run identifier
+    report_id: Optional[str]       # Report ID (if report created)
+    status: str                    # "pending", "processing", "completed", "failed"
+    
+    # Dataset metadata
+    dataset_title: Optional[str]           # Dataset title
+    dataset_description: Optional[str]    # Dataset description
+    total_rows: Optional[int]              # Number of rows in dataset
+    target_column: Optional[str]           # Name of target column
+    task: Optional[str]                    # "regression", "binary_classification", or "multiclass_classification"
+    
+    # LLM-generated summary
+    summary: Optional[Summary]             # Summary object with overview, insights, etc.
+    
+    # Discovered patterns
+    patterns: List[Pattern]                 # List of discovered patterns
+    
+    # Column/feature information
+    columns: List[Column]                  # List of columns with statistics and importance
+    
+    # Correlation matrix
+    correlation_matrix: List[CorrelationEntry]  # Feature correlations
+    
+    # Global feature importance
+    feature_importance: Optional[FeatureImportance]  # Feature importance scores
+    
+    # Job tracking
+    job_id: Optional[str]           # Job ID for tracking processing
+    job_status: Optional[str]      # Job status
+    error_message: Optional[str]   # Error message if analysis failed
+```
+
+### Summary
+
+```python
+@dataclass
+class Summary:
+    overview: str                          # High-level explanation of findings
+    key_insights: List[str]                # List of main takeaways
+    novel_patterns: PatternGroup           # Novel pattern explanations
+    surprising_findings: PatternGroup      # Surprising findings
+    statistically_significant: PatternGroup  # Statistically significant patterns
+    data_insights: Optional[DataInsights]  # Important features, correlations
+    selected_pattern_id: Optional[str]     # ID of selected pattern
+```
+
+### Pattern
+
+```python
+@dataclass
+class Pattern:
+    id: str                                # Pattern identifier
+    task: str                              # Task type
+    target_column: str                     # Target column name
+    direction: str                         # "min" or "max"
+    p_value: float                         # Statistical p-value
+    conditions: List[Dict]                 # Pattern conditions (continuous, categorical, datetime)
+    lift_value: float                      # Lift value (how much the pattern increases/decreases target)
+    support_count: int                     # Number of rows matching pattern
+    support_percentage: float              # Percentage of rows matching pattern
+    pattern_type: str                      # "validated" or "speculative"
+    novelty_type: str                      # "novel" or "confirmatory"
+    target_score: float                    # Target score for this pattern
+    description: str                       # Human-readable description
+    novelty_explanation: str               # Explanation of novelty
+    target_class: Optional[str]            # Target class (for classification)
+    target_mean: Optional[float]           # Target mean (for regression)
+    target_std: Optional[float]            # Target standard deviation
+    citations: List[Dict]                  # Academic citations
+```
+
+### Column
+
+```python
+@dataclass
+class Column:
+    id: str                                # Column identifier
+    name: str                              # Column name
+    display_name: str                      # Display name
+    type: str                              # "continuous" or "categorical"
+    data_type: str                         # "int", "float", "string", "boolean", "datetime"
+    enabled: bool                          # Whether column is enabled
+    description: Optional[str]              # Column description
+    
+    # Statistics
+    mean: Optional[float]                  # Mean value
+    median: Optional[float]                 # Median value
+    std: Optional[float]                   # Standard deviation
+    min: Optional[float]                   # Minimum value
+    max: Optional[float]                   # Maximum value
+    iqr_min: Optional[float]               # IQR minimum
+    iqr_max: Optional[float]               # IQR maximum
+    mode: Optional[str]                    # Mode value
+    approx_unique: Optional[int]           # Approximate unique count
+    null_percentage: Optional[float]      # Percentage of null values
+    
+    # Feature importance
+    feature_importance_score: Optional[float]  # Feature importance score
+```
+
+### FeatureImportance
+
+```python
+@dataclass
+class FeatureImportance:
+    kind: str                              # Feature importance type: "global" 
+    baseline: float                        # Baseline model output
+    scores: List[FeatureImportanceScore]   # List of feature scores
+```
+
+### CorrelationEntry
+
+```python
+@dataclass
+class CorrelationEntry:
+    feature_x: str                         # First feature name
+    feature_y: str                         # Second feature name
+    value: float                           # Correlation value (-1 to 1)
+```
+
+### Pattern
+
+```python
+@dataclass
+class Pattern:
+    id: str
+    task: str
+    target_column: str
+    direction: str  # "min" or "max"
+    p_value: float
+    conditions: List[Dict]  # Continuous, categorical, or datetime conditions
+    lift_value: float
+    support_count: int
+    support_percentage: float
+    pattern_type: str  # "validated" or "speculative"
+    novelty_type: str  # "novel" or "confirmatory"
+    target_score: float
+    description: str
+    novelty_explanation: str
+    target_class: Optional[str]
+    target_mean: Optional[float]
+    target_std: Optional[float]
+    citations: List[Dict]
+```
+

discovery_engine_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+discovery/__init__.py,sha256=3A09KLiF4vW1oQFpRgv2iuyfmLXar9LbbNNY4i1DBZ8,624
+discovery/client.py,sha256=oZz4eTP3K8jKfYmDkBzvr_7MTKZCtnA2b3DlUmW-ObI,26857
+discovery/types.py,sha256=4Z3gKdxWnOpymEjBGCzAeUGjwRT2A0aCpmuwctbE4w0,6008
+discovery_engine_api-0.1.0.dist-info/METADATA,sha256=C_0ZJlvrIZGRNuVfPJznVjU-ywDAfEJ5eT4O42Scats,11739
+discovery_engine_api-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+discovery_engine_api-0.1.0.dist-info/RECORD,,

discovery_engine_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any