quercle 0.1.2

Official Python SDK for the Quercle API - AI-powered web search and fetching

Quercle Python SDK

Official Python SDK for the Quercle API - AI-powered web search and fetching.

Installation

uv add quercle

Quick Start

from quercle import QuercleClient

# Initialize with API key (or set QUERCLE_API_KEY env var)
client = QuercleClient(api_key="qk_...")

# Fetch and analyze a URL
result = client.fetch(
    url="<any-url>",
    prompt="Summarize the main points in bullet points"
)
print(result)

# Search the web
result = client.search("What is TypeScript?")
print(result)

Authentication

Get your API key at quercle.dev.

# Option 1: Pass API key directly
client = QuercleClient(api_key="qk_...")

# Option 2: Set environment variable
# export QUERCLE_API_KEY=qk_...
client = QuercleClient()

Usage

Synchronous Client

from quercle import QuercleClient

# Using context manager (recommended)
with QuercleClient() as client:
    # Fetch a URL and analyze content
    result = client.fetch(
        url="<any-url>",
        prompt="Extract the main heading and first paragraph"
    )
    print(result)

    # Search the web
    result = client.search("Python best practices 2024")
    print(result)

    # Search with domain filtering
    result = client.search(
        "machine learning tutorials",
        allowed_domains=["*.edu", "*.org"],
        blocked_domains=["*.xyz"]
    )
    print(result)

Asynchronous Client

import asyncio
from quercle import AsyncQuercleClient

async def main():
    async with AsyncQuercleClient() as client:
        # Fetch
        result = await client.fetch(
            url="<any-url>",
            prompt="Summarize this page"
        )
        print(result)

        # Search
        result = await client.search("Latest AI news")
        print(result)

        # Parallel requests
        results = await asyncio.gather(
            client.search("Python tutorials"),
            client.search("TypeScript tutorials"),
        )
        for r in results:
            print(r)

asyncio.run(main())

API Reference

QuercleClient / AsyncQuercleClient

Constructor

QuercleClient(
    api_key: str | None = None,      # API key (or use QUERCLE_API_KEY env var)
    timeout: float | None = None,    # Request timeout in seconds (default: 120)
)

Methods

fetch(url: str, prompt: str) -> str

Fetch a URL and analyze its content with AI.

• url: The URL to fetch and analyze
• prompt: Instructions for how to analyze the page content
• Returns: AI-processed analysis of the page content

search(query: str, *, allowed_domains: list[str] | None = None, blocked_domains: list[str] | None = None) -> str

Search the web and get AI-synthesized answers with citations.

• query: The search query
• allowed_domains: Only include results from these domains (e.g., ["*.edu", "*.gov"])
• blocked_domains: Exclude results from these domains
• Returns: AI-synthesized answer with source citations

Error Handling

from quercle import QuercleClient, QuercleError
from quercle.exceptions import (
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
    TimeoutError,
)

try:
    client = QuercleClient()
    result = client.search("test query")
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError:
    print("Not enough credits")
except RateLimitError:
    print("Too many requests")
except TimeoutError:
    print("Request timed out")
except QuercleError as e:
    print(f"API error: {e.status_code} - {e.detail}")

Tool Descriptions

Pre-defined descriptions for building AI agent tools:

from quercle import (
    # Tool descriptions
    FETCH_TOOL_DESCRIPTION,
    SEARCH_TOOL_DESCRIPTION,
    # Fetch field descriptions
    FETCH_URL_DESCRIPTION,
    FETCH_PROMPT_DESCRIPTION,
    # Search field descriptions
    SEARCH_QUERY_DESCRIPTION,
    SEARCH_ALLOWED_DOMAINS_DESCRIPTION,
    SEARCH_BLOCKED_DOMAINS_DESCRIPTION,
)

Constant	Description
FETCH_TOOL_DESCRIPTION	Fetch a web page and analyze its content using AI...
SEARCH_TOOL_DESCRIPTION	Search the web and get an AI-synthesized answer with citations...
FETCH_URL_DESCRIPTION	The URL to fetch and analyze
FETCH_PROMPT_DESCRIPTION	Instructions for how to analyze the page content...
SEARCH_QUERY_DESCRIPTION	The search query to find information about. Be specific
SEARCH_ALLOWED_DOMAINS_DESCRIPTION	Only include results from these domains...
SEARCH_BLOCKED_DOMAINS_DESCRIPTION	Exclude results from these domains...

Requirements

• Python 3.10+
• httpx

License

MIT