Python SDK

Typed Python client. Sync and async support. Python 3.9+.

Install

pip install ilmenite

Quickstart

from ilmenite import Ilmenite

client = Ilmenite(api_key="il_live_...")

result = client.scrape(
    url="https://news.ycombinator.com",
    formats=["markdown", "links"],
)

print(result.markdown)
print(f"{len(result.links)} links in {result.latency_ms}ms")

Async

import asyncio
from ilmenite import AsyncIlmenite

async def main():
    async with AsyncIlmenite(api_key="il_live_...") as client:
        results = await asyncio.gather(
            client.scrape(url="https://news.ycombinator.com"),
            client.scrape(url="https://lobste.rs"),
        )
        for r in results:
            print(r.title, r.latency_ms)

asyncio.run(main())

Extract with Pydantic

from pydantic import BaseModel
from ilmenite import Ilmenite

class Product(BaseModel):
    name: str
    price_usd: float
    in_stock: bool

client = Ilmenite()
result = client.extract(
    url="https://example.com/product/42",
    schema=Product,  # auto-converted to JSON Schema
)

product: Product = result.data
print(product.price_usd)

Configuration

The client reads ILMENITE_API_KEY from the environment if not passed.

client = Ilmenite(
    api_key="il_live_...",
    base_url="https://api.ilmenite.dev",  # override for self-hosted
    timeout=30.0,
    max_retries=3,
)

Errors

from ilmenite import IlmeniteError, RateLimitError, TimeoutError

try:
    result = client.scrape(url="https://slow-site.com", timeout_ms=5000)
except RateLimitError as e:
    time.sleep(e.retry_after_ms / 1000)
except TimeoutError:
    print("page did not finish in time")
except IlmeniteError as e:
    print(f"{e.code}: {e.message}")