Metadata-Version: 2.4
Name: trawl-sdk
Version: 0.1.1
Summary: Python SDK for the Trawl unified content API
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Trawl Python SDK

The official Python SDK for the [Trawl](https://gettrawl.com) API — extract transcripts from YouTube, podcasts, TikTok, earnings calls, SEC filings, news, and academic papers.

## Install

```bash
pip install trawl
```

## Quick Start

```python
from trawl import TrawlClient

client = TrawlClient(api_key="trawl_your_key")

# Search YouTube
results = client.search.youtube("machine learning tutorial", max_results=5)
for video in results.results:
    print(f"{video.title} — {video.channel}")

# Extract a transcript
transcript = client.transcripts.extract("https://youtube.com/watch?v=dQw4w9WgXcQ")
print(f"{len(transcript.segments)} segments extracted")

# Preview without auth (free)
preview = client.transcripts.preview("https://youtube.com/watch?v=dQw4w9WgXcQ")

# Bulk download as ZIP
zip_bytes = client.bulk.download(["dQw4w9WgXcQ", "9bZkp7q19f0"], format="jsonl")
```

## All Resources

```python
client = TrawlClient(api_key="trawl_your_key")

# YouTube
client.search.youtube(query, max_results=10)
client.transcripts.extract(url, language=None)
client.transcripts.preview(url)              # No auth needed
client.transcripts.download(id, format="txt")
client.bulk.download(video_ids, format="txt") # No auth needed

# Podcasts
client.search.podcasts(query, max_results=20)
client.podcasts.episodes(podcast_id)
client.podcasts.transcribe(audio_url)

# Earnings Calls
client.earnings.search("AAPL")
client.earnings.get_transcript("AAPL", 2026, 1)
client.earnings.get_chunks("AAPL", 2026, 1)

# SEC Filings
client.filings.search("AAPL", form_type="10-K")

# News (GDELT)
client.news.search("Federal Reserve", language="en")
client.news.get_article_text("https://example.com/article")

# Academic Papers
client.papers.search("transformer architecture")
client.papers.extract(arxiv_id="2301.08745")

# AI Analysis
client.ai.summarize(transcript_id)
client.ai.topics(transcript_id)
client.ai.entities(transcript_id)
client.ai.preview_summarize("Raw text to summarize")  # No auth

# Jobs
client.jobs.get(job_id)
client.jobs.list()
```

## Error Handling

```python
from trawl.exceptions import (
    TrawlError,
    AuthenticationError,  # 401
    NotFoundError,        # 404
    RateLimitError,       # 429
    ValidationError,      # 422
)

try:
    transcript = client.transcripts.extract("invalid-url")
except ValidationError as e:
    print(f"Bad request: {e}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
```

## Context Manager

```python
with TrawlClient(api_key="trawl_your_key") as client:
    results = client.search.youtube("python")
    # client.close() called automatically
```

## Requirements

- Python 3.10+
- httpx

## Links

- [API Documentation](https://gettrawl.com/docs)
- [RAG Pipeline Tutorial](https://gettrawl.com/blog/youtube-rag-pipeline)
- [GitHub](https://github.com/trawl/trawl)
