# ihyee

[![PyPI](https://img.shields.io/pypi/v/ihyee)](https://pypi.org/project/ihyee/)
[![Python](https://img.shields.io/pypi/pyversions/ihyee)](https://pypi.org/project/ihyee/)
[![License](https://img.shields.io/pypi/l/ihyee)](https://github.com/aizukanne/ihyee-python/blob/main/LICENSE)

**Python SDK for the ihyee web intelligence API** — search, fetch, and understand any web page in one API call.

## Install

```bash
pip install ihyee
```

## Quick Start

```python
from ihyee import Ihyee

client = Ihyee(api_key="your_api_key")
results = client.search("transformer architecture", max_results=3)

for item in results.content:
    if item.type == "text" and item.text:
        print(item.text.summary)
```

## Search

Search the web via Google and return extracted, summarized content from top results.

```python
results = client.search(
    "latest AI research",
    max_results=5,
    content_mode="both",      # "both", "full_text", or "summary"
    before="2026-01-01",       # date filters
    must_have="transformer",   # exact phrase required
)

for item in results.content:
    if item.type == "text":
        print(f"URL: {item.url}")
        print(f"Summary: {item.text.summary}")
        print(f"Links: {len(item.text.links)}")
    elif item.type == "image_url":
        print(f"Image: {item.image_url.url}")
```

## Fetch

Fetch and extract content from specific URLs. Automatically uses headless browser rendering for JavaScript-heavy pages.

```python
results = client.fetch(
    ["https://example.com/article", "https://spa-app.com/page"],
    content_mode="full_text",
)
```

## Render

Force full browser rendering with Playwright. Use for SPAs and pages that require JavaScript.

```python
results = client.render(
    "https://spa-app.com/dashboard",
    wait_for="networkidle",
    wait_selector="#content",
    timeout_ms=30000,
)
```

## Async Usage

```python
from ihyee import AsyncIhyee

async with AsyncIhyee(api_key="your_key") as client:
    results = await client.search("transformer architecture")
    print(results.content[0].text.summary)
```

## Error Handling

```python
from ihyee import Ihyee, AuthError, RateLimitError, IhyeeError

try:
    results = client.search("query")
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except IhyeeError as e:
    print(f"API error {e.code}: {e.message}")
```

## Environment Variable

```bash
# Set IHYEE_API_KEY in your environment
export IHYEE_API_KEY=your_api_key
```

```python
# Then omit api_key parameter
client = Ihyee()
```

## Documentation

Full API docs: [ihyee.delta-telematics.ca/api-docs](https://ihyee.delta-telematics.ca/api-docs)

## License

MIT
