Discovery Engine Python SDK

Python client library for the Discovery Engine API.

Installation

pip install leap-discovery-client

For pandas DataFrame support:

pip install leap-discovery-client[pandas]

Quick Start

from discovery import Client

# Initialize client - automatically uses the production API
client = Client(api_key="your-api-key")

# Analyze a dataset and wait for results
result = client.analyze(
    file="data.csv",
    target_column="price",
    mode="fast",
    description="House price dataset from Kaggle",
    column_descriptions={
        "age": "Age of the house in years",
        "price": "Sale price in USD"
    },
    visibility="public",
    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")

Features

• Simple API: Single analyze() method handles the entire workflow
• Complete Results: Returns everything shown in the Discovery dashboard
• Pandas Support: Upload DataFrames directly with automatic column inference
• Async Support: Use analyze_async() for async workflows
• Polling: Automatically wait for completion with configurable timeout

What You Get Back

The SDK returns an AnalysisResult with everything the Discovery dashboard shows:

Summary (LLM-generated)

result.summary.overview           # High-level explanation of findings
result.summary.key_insights       # List of main takeaways
result.summary.novel_patterns     # Novel pattern explanations
result.summary.surprising_findings
result.summary.statistically_significant
result.summary.data_insights      # Important features, correlations

Patterns

for pattern in result.patterns:
    print(f"Pattern {pattern.id}: {pattern.description}")
    print(f"  Direction: {pattern.direction}")
    print(f"  Lift: {pattern.lift_value}")
    print(f"  Support: {pattern.support_count} ({pattern.support_percentage:.1%})")
    print(f"  P-value: {pattern.p_value}")
    print(f"  Type: {pattern.pattern_type} / {pattern.novelty_type}")
    print(f"  Conditions: {pattern.conditions}")
    print(f"  Citations: {len(pattern.citations)}")

Columns with Feature Importance

for col in result.columns:
    print(f"{col.display_name}")
    print(f"  Type: {col.type} ({col.data_type})")
    print(f"  Stats: mean={col.mean}, std={col.std}, min={col.min}, max={col.max}")
    print(f"  Null %: {col.null_percentage}")
    if col.feature_importance_score:
        print(f"  Importance: {col.feature_importance_score}")

Correlation Matrix

for entry in result.correlation_matrix:
    print(f"{entry.feature_x} <-> {entry.feature_y}: {entry.value:.3f}")

Feature Importance

if result.feature_importance:
    print(f"Model type: {result.feature_importance.kind}")
    print(f"Baseline: {result.feature_importance.baseline}")
    for score in result.feature_importance.scores:
        print(f"  {score.feature}: {score.score}")

Configuration

The client automatically uses the production API endpoint. For testing or custom deployments, you can override the URL via the DISCOVERY_API_URL environment variable:

export DISCOVERY_API_URL="https://custom-api.example.com"

Configuration Options

All dashboard options are supported:

Async Usage

import asyncio
from discovery import Client

async def main():
    async with Client(api_key="...") as client:
        # Start analysis without waiting
        result = await client.analyze_async(
            file=df,
            target_column="target"
        )
        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)

asyncio.run(main())

Step-by-Step API

For more control, use the individual methods:

# 1. Upload file
file_info = await client.upload_file("data.csv")

# 2. Create dataset
dataset = await client.create_dataset(
    title="My Dataset",
    description="...",
    total_rows=1000
)

# 3. Link file to dataset
await client.create_file_record(dataset["id"], file_info)

# 4. Define columns
columns = await client.create_columns(dataset["id"], [
    {"name": "age", "display_name": "Age", "type": "continuous", ...},
    {"name": "price", "display_name": "Price", "type": "continuous", ...},
])

# 5. Start run
run = await client.create_run(
    dataset["id"],
    target_column_id=columns[1]["id"],
    task="regression",
    mode="fast"
)

# 6. Get results
result = await client.get_results(run["id"])

Data Types

AnalysisResult

@dataclass
class AnalysisResult:
    run_id: str
    report_id: Optional[str]
    status: str  # "pending", "processing", "completed", "failed"
    
    # Dataset metadata
    dataset_title: Optional[str]
    dataset_description: Optional[str]
    total_rows: Optional[int]
    target_column: Optional[str]
    task: Optional[str]
    
    # Results
    summary: Optional[Summary]
    patterns: List[Pattern]
    columns: List[Column]
    correlation_matrix: List[CorrelationEntry]
    feature_importance: Optional[FeatureImportance]
    
    # Job tracking
    job_id: Optional[str]
    job_status: Optional[str]
    error_message: Optional[str]

Pattern

@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]

Column

@dataclass
class Column:
    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]
    
    # Statistics
    mean: Optional[float]
    median: Optional[float]
    std: Optional[float]
    min: Optional[float]
    max: Optional[float]
    iqr_min: Optional[float]
    iqr_max: Optional[float]
    mode: Optional[str]
    approx_unique: Optional[int]
    null_percentage: Optional[float]
    
    # Feature importance
    feature_importance_score: Optional[float]