Metadata-Version: 2.4
Name: mindcase
Version: 0.2.0
Summary: Python SDK for the Mindcase Developer API
Project-URL: Homepage, https://mindcase.co
Project-URL: Documentation, https://docs.mindcase.co
Project-URL: Repository, https://github.com/mindcase-team/studio
License-Expression: MIT
Requires-Python: >=3.8
Requires-Dist: requests>=2.25.0
Description-Content-Type: text/markdown

# Mindcase Python SDK

Official Python SDK for the [Mindcase Developer API](https://docs.mindcase.co) — programmatic access to 34+ data collection agents across Instagram, LinkedIn, Amazon, YouTube, Google Maps, and more.

## Installation

```bash
pip install mindcase
```

## Quick Start

```python
from mindcase import MindcaseClient

client = MindcaseClient("mk_live_...")

# List available agent groups
groups = client.list_groups()
# ['instagram', 'linkedin', 'amazon', 'youtube', ...]

# List agents in a group
agents = client.list_agents("instagram")

# Run an agent and wait for results
results = client.run_and_wait(
    "instagram", "profile-scraper",
    usernames=["nike", "adidas"]
)

for row in results:
    print(row["Username"], row["Followers"])
```

## Authentication

Get your API key from the [Mindcase Dashboard](https://mindcase.co/settings) under **Developer > API Keys**.

```python
client = MindcaseClient("mk_live_your_key_here")
```

## Usage

### Discover Agents

```python
# List all groups
groups = client.list_groups()

# List agents in a group
agents = client.list_agents("linkedin")
for agent in agents:
    print(agent.name, agent.slug, agent.credits_per_row)

# Get agent details and parameter schema
agent = client.get_agent("linkedin", "profile-scraper")
print(agent.name)             # "LinkedIn Profile Scraper"
print(agent.required_params)  # {'profileUrls': Parameter(...)}
print(agent.credits_per_row)  # 2
```

### Run Agents

```python
# Run an agent — returns immediately with a Job object
job = client.run("amazon", "product-scraper", searchTerms=["laptop stand"])
print(job.job_id)   # "job_abc123"
print(job.status)   # "queued"

# Then poll for results manually
results = client.wait_for_results(job.job_id)
```

```python
# Or run and wait for results in one call (polls automatically)
results = client.run_and_wait(
    "amazon", "product-scraper",
    searchTerms=["laptop stand"],
    timeout=300,          # max wait in seconds (default 300)
    poll_interval=3.0,    # seconds between polls (default 3)
)
print(f"Got {results.row_count} rows")
for row in results:
    print(row["Title"], row["Price"])
```

### Job Management

```python
# Check job status
job = client.get_job("job_abc123")
print(job.status)      # queued, running, completed, failed, cancelled
print(job.is_done)     # True if completed
print(job.is_running)  # True if queued or running

# Get results for a completed job
results = client.get_results("job_abc123")
print(results.columns)              # ['Title', 'Price', ...]
print(results.to_list("Title"))     # ['Laptop Stand', ...]
print(results[0])                   # first row as dict

# Cancel a running job
client.cancel_job("job_abc123")

# List your recent jobs
jobs = client.list_jobs(limit=10)
jobs = client.list_jobs(status="completed")
```

### Check Credits

```python
credits = client.get_credits()
print(f"{credits} credits remaining")
```

## Error Handling

```python
from mindcase import (
    MindcaseError,
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
    NotFoundError,
    ValidationError,
)

try:
    results = client.run_and_wait("instagram", "profile-scraper", usernames=["nike"])
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError:
    print("Not enough credits — top up at mindcase.co")
except RateLimitError:
    print("Too many requests — retry after 60s")
except NotFoundError:
    print("Agent not found")
except ValidationError as e:
    print(f"Bad parameters: {e.message}")
except MindcaseError as e:
    print(f"API error {e.status_code}: {e.message}")
```

## Configuration

```python
client = MindcaseClient(
    api_key="mk_live_...",
    base_url="https://api.mindcase.co/api/v1",  # default
    timeout=30,                                   # request timeout in seconds
)
```

## Links

- [Documentation](https://docs.mindcase.co)
- [Dashboard](https://mindcase.co)
- [GitHub](https://github.com/mindcase-team/studio)

## License

MIT
