dolfi-python-sdk

Name	dolfi-python-sdk JSON
Version	1.0.0 JSON
	download
home_page	https://github.com/dolfi/dolfi-python-sdk
Summary	Python SDK for the Dolfi API - search and web scraping made simple
upload_time	2025-08-19 04:13:32
maintainer	None
docs_url	None
author	Dolfi SDK Team
requires_python	>=3.8
license	MIT
keywords	dolfi api sdk search web scraping scraping web content extraction ai search natural language search
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Dolfi Python SDK

[![PyPI version](https://badge.fury.io/py/dolfi-python-sdk.svg)](https://badge.fury.io/py/dolfi-python-sdk)
[![Python Support](https://img.shields.io/pypi/pyversions/dolfi-python-sdk.svg)](https://pypi.org/project/dolfi-python-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An easy-to-use Python SDK for the Dolfi API that provides intelligent web search and content scraping capabilities.

## Features

- **🔍 AI-Powered Search**: Natural language web search with AI-generated summaries
- **🕷️ Web Scraping**: Extract content from web pages in markdown or text format
- **🌐 Multi-language Support**: Search and get answers in 20+ languages
- **⚡ Async Support**: Both synchronous and asynchronous client implementations
- **🔒 Type Safety**: Full type hints and Pydantic model validation
- **🛡️ Error Handling**: Comprehensive exception handling with detailed error messages

## Installation

```bash
pip install dolfi-python-sdk
```

## Quick Start

### Search Example

```python
from dolfi_sdk import DolfiClient

# Initialize the client
client = DolfiClient(api_key="your-api-key-here")

# Perform a search
response = client.search(
    query="What are the latest developments in AI?",
    max_results=5,
    include_answer=True
)

print(f"AI Answer: {response.answer}")
for result in response.results:
    print(f"- {result.title}: {result.url}")
```

### Scraping Example

```python
# Scrape content from web pages
response = client.scrape(
    urls=["https://example.com", "https://another-site.com"],
    format="markdown",
    ignore_links=False
)

for result in response.results:
    if result.status == 200:
        print(f"Content from {result.url}:")
        print(result.formatted_content[:500] + "...")
```

### Async Usage

```python
import asyncio
from dolfi_sdk import AsyncDolfiClient

async def main():
    async with AsyncDolfiClient(api_key="your-api-key-here") as client:
        # Async search
        search_response = await client.search("Python programming best practices")
        
        # Async scraping
        scrape_response = await client.scrape("https://python.org")
        
        print(f"Found {search_response.num_of_results} results")
        print(f"Scraped {len(scrape_response.results)} pages")

asyncio.run(main())
```

## API Reference

### DolfiClient

The main synchronous client for interacting with the Dolfi API.

#### Methods

##### `search(query, **kwargs) -> SearchResponse`

Perform an intelligent web search with optional AI-generated answers.

**Parameters:**
- `query` (str): Natural language search query (max 400 characters)
- `max_results` (int, optional): Maximum number of results (1-20, default: 5)
- `time_range` (str, optional): Filter by time period ("day", "month", "year")
- `search_language` (str, optional): Language code for search (default: "en")
- `include_answer` (bool, optional): Include AI-generated summary (default: True)
- `answer_language` (str, optional): Language code for AI answer (default: "en")
- `answer_instruction` (str, optional): Custom instructions for AI answer formatting

##### `scrape(urls, **kwargs) -> ScrapeResponse`

Scrape content from one or more web pages.

**Parameters:**
- `urls` (str | List[str]): Single URL or list of URLs to scrape
- `format` (str, optional): Output format ("markdown" or "text", default: "markdown")
- `ignore_links` (bool, optional): Exclude hyperlinks from output (default: False)
- `ignore_images` (bool, optional): Exclude images from output (default: False)
- `mobile` (bool, optional): Use mobile version of websites (default: False)

### AsyncDolfiClient

Asynchronous client with the same interface as `DolfiClient`, but all methods are `async`.

### Response Models

#### SearchResponse
- `id`: Unique identifier for the search
- `query`: Original search query
- `num_of_results`: Total number of results found
- `answer`: AI-generated summary answer
- `search_words`: Optimized search keywords used
- `results`: List of `SearchResultItem` objects
- `turn_around`: Processing time in seconds

#### ScrapeResponse
- `id`: Unique identifier for the scraping operation
- `request_format`: Requested output format
- `results`: List of `ScrapeResponseItem` objects
- `turn_around`: Processing time in seconds

### Supported Languages

The SDK supports 20+ languages for both search and AI answers:

`zh` (Chinese), `en` (English), `hi` (Hindi), `es` (Spanish), `ar` (Arabic), `fr` (French), `bn` (Bengali), `pt` (Portuguese), `ru` (Russian), `ja` (Japanese), `pa` (Punjabi), `de` (German), `jv` (Javanese), `ko` (Korean), `vi` (Vietnamese), `te` (Telugu), `mr` (Marathi), `tr` (Turkish), `ta` (Tamil), `ur` (Urdu)

## Error Handling

The SDK provides specific exception types for different error scenarios:

```python
from dolfi_sdk import (
    DolfiAuthenticationError,
    DolfiValidationError, 
    DolfiAPIError,
    DolfiConnectionError,
    DolfiTimeoutError
)

try:
    response = client.search("example query")
except DolfiAuthenticationError:
    print("Invalid API key")
except DolfiValidationError as e:
    print(f"Invalid request: {e.message}")
except DolfiAPIError as e:
    print(f"API error: {e.message} (Status: {e.status_code})")
except DolfiConnectionError:
    print("Connection failed")
except DolfiTimeoutError:
    print("Request timed out")
```

## Configuration

### Environment Variables

You can set your API key as an environment variable:

```bash
export DOLFI_API_KEY="your-api-key-here"
```

```python
import os
from dolfi_sdk import DolfiClient

client = DolfiClient(api_key=os.getenv("DOLFI_API_KEY"))
```

### Custom Base URL

For enterprise or custom deployments:

```python
client = DolfiClient(
    api_key="your-api-key",
    base_url="https://your-custom-api.com",
    timeout=60
)
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 📧 Email: support@dolfi.com
- 📖 Documentation: https://docs.dolfi.com
- 🐛 Issues: https://github.com/dolfi/dolfi-python-sdk/issues

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this package.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/dolfi/dolfi-python-sdk",
    "name": "dolfi-python-sdk",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "Dolfi SDK Team <support@dolfi.com>",
    "keywords": "dolfi, api, sdk, search, web scraping, scraping, web, content extraction, ai search, natural language search",
    "author": "Dolfi SDK Team",
    "author_email": "Dolfi SDK Team <support@dolfi.com>",
    "download_url": "https://files.pythonhosted.org/packages/c0/5b/630b8c4f73a9372db43e79b99fe3812405844affc78f20edb93ed01c9f4d/dolfi_python_sdk-1.0.0.tar.gz",
    "platform": null,
    "description": "# Dolfi Python SDK\n\n[![PyPI version](https://badge.fury.io/py/dolfi-python-sdk.svg)](https://badge.fury.io/py/dolfi-python-sdk)\n[![Python Support](https://img.shields.io/pypi/pyversions/dolfi-python-sdk.svg)](https://pypi.org/project/dolfi-python-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nAn easy-to-use Python SDK for the Dolfi API that provides intelligent web search and content scraping capabilities.\n\n## Features\n\n- **\ud83d\udd0d AI-Powered Search**: Natural language web search with AI-generated summaries\n- **\ud83d\udd77\ufe0f Web Scraping**: Extract content from web pages in markdown or text format\n- **\ud83c\udf10 Multi-language Support**: Search and get answers in 20+ languages\n- **\u26a1 Async Support**: Both synchronous and asynchronous client implementations\n- **\ud83d\udd12 Type Safety**: Full type hints and Pydantic model validation\n- **\ud83d\udee1\ufe0f Error Handling**: Comprehensive exception handling with detailed error messages\n\n## Installation\n\n```bash\npip install dolfi-python-sdk\n```\n\n## Quick Start\n\n### Search Example\n\n```python\nfrom dolfi_sdk import DolfiClient\n\n# Initialize the client\nclient = DolfiClient(api_key=\"your-api-key-here\")\n\n# Perform a search\nresponse = client.search(\n    query=\"What are the latest developments in AI?\",\n    max_results=5,\n    include_answer=True\n)\n\nprint(f\"AI Answer: {response.answer}\")\nfor result in response.results:\n    print(f\"- {result.title}: {result.url}\")\n```\n\n### Scraping Example\n\n```python\n# Scrape content from web pages\nresponse = client.scrape(\n    urls=[\"https://example.com\", \"https://another-site.com\"],\n    format=\"markdown\",\n    ignore_links=False\n)\n\nfor result in response.results:\n    if result.status == 200:\n        print(f\"Content from {result.url}:\")\n        print(result.formatted_content[:500] + \"...\")\n```\n\n### Async Usage\n\n```python\nimport asyncio\nfrom dolfi_sdk import AsyncDolfiClient\n\nasync def main():\n    async with AsyncDolfiClient(api_key=\"your-api-key-here\") as client:\n        # Async search\n        search_response = await client.search(\"Python programming best practices\")\n        \n        # Async scraping\n        scrape_response = await client.scrape(\"https://python.org\")\n        \n        print(f\"Found {search_response.num_of_results} results\")\n        print(f\"Scraped {len(scrape_response.results)} pages\")\n\nasyncio.run(main())\n```\n\n## API Reference\n\n### DolfiClient\n\nThe main synchronous client for interacting with the Dolfi API.\n\n#### Methods\n\n##### `search(query, **kwargs) -> SearchResponse`\n\nPerform an intelligent web search with optional AI-generated answers.\n\n**Parameters:**\n- `query` (str): Natural language search query (max 400 characters)\n- `max_results` (int, optional): Maximum number of results (1-20, default: 5)\n- `time_range` (str, optional): Filter by time period (\"day\", \"month\", \"year\")\n- `search_language` (str, optional): Language code for search (default: \"en\")\n- `include_answer` (bool, optional): Include AI-generated summary (default: True)\n- `answer_language` (str, optional): Language code for AI answer (default: \"en\")\n- `answer_instruction` (str, optional): Custom instructions for AI answer formatting\n\n##### `scrape(urls, **kwargs) -> ScrapeResponse`\n\nScrape content from one or more web pages.\n\n**Parameters:**\n- `urls` (str | List[str]): Single URL or list of URLs to scrape\n- `format` (str, optional): Output format (\"markdown\" or \"text\", default: \"markdown\")\n- `ignore_links` (bool, optional): Exclude hyperlinks from output (default: False)\n- `ignore_images` (bool, optional): Exclude images from output (default: False)\n- `mobile` (bool, optional): Use mobile version of websites (default: False)\n\n### AsyncDolfiClient\n\nAsynchronous client with the same interface as `DolfiClient`, but all methods are `async`.\n\n### Response Models\n\n#### SearchResponse\n- `id`: Unique identifier for the search\n- `query`: Original search query\n- `num_of_results`: Total number of results found\n- `answer`: AI-generated summary answer\n- `search_words`: Optimized search keywords used\n- `results`: List of `SearchResultItem` objects\n- `turn_around`: Processing time in seconds\n\n#### ScrapeResponse\n- `id`: Unique identifier for the scraping operation\n- `request_format`: Requested output format\n- `results`: List of `ScrapeResponseItem` objects\n- `turn_around`: Processing time in seconds\n\n### Supported Languages\n\nThe SDK supports 20+ languages for both search and AI answers:\n\n`zh` (Chinese), `en` (English), `hi` (Hindi), `es` (Spanish), `ar` (Arabic), `fr` (French), `bn` (Bengali), `pt` (Portuguese), `ru` (Russian), `ja` (Japanese), `pa` (Punjabi), `de` (German), `jv` (Javanese), `ko` (Korean), `vi` (Vietnamese), `te` (Telugu), `mr` (Marathi), `tr` (Turkish), `ta` (Tamil), `ur` (Urdu)\n\n## Error Handling\n\nThe SDK provides specific exception types for different error scenarios:\n\n```python\nfrom dolfi_sdk import (\n    DolfiAuthenticationError,\n    DolfiValidationError, \n    DolfiAPIError,\n    DolfiConnectionError,\n    DolfiTimeoutError\n)\n\ntry:\n    response = client.search(\"example query\")\nexcept DolfiAuthenticationError:\n    print(\"Invalid API key\")\nexcept DolfiValidationError as e:\n    print(f\"Invalid request: {e.message}\")\nexcept DolfiAPIError as e:\n    print(f\"API error: {e.message} (Status: {e.status_code})\")\nexcept DolfiConnectionError:\n    print(\"Connection failed\")\nexcept DolfiTimeoutError:\n    print(\"Request timed out\")\n```\n\n## Configuration\n\n### Environment Variables\n\nYou can set your API key as an environment variable:\n\n```bash\nexport DOLFI_API_KEY=\"your-api-key-here\"\n```\n\n```python\nimport os\nfrom dolfi_sdk import DolfiClient\n\nclient = DolfiClient(api_key=os.getenv(\"DOLFI_API_KEY\"))\n```\n\n### Custom Base URL\n\nFor enterprise or custom deployments:\n\n```python\nclient = DolfiClient(\n    api_key=\"your-api-key\",\n    base_url=\"https://your-custom-api.com\",\n    timeout=60\n)\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udce7 Email: support@dolfi.com\n- \ud83d\udcd6 Documentation: https://docs.dolfi.com\n- \ud83d\udc1b Issues: https://github.com/dolfi/dolfi-python-sdk/issues\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a history of changes to this package.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Python SDK for the Dolfi API - search and web scraping made simple",
    "version": "1.0.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/dolfi/dolfi-python-sdk/issues",
        "Documentation": "https://docs.dolfi.com",
        "Homepage": "https://dolfi.com",
        "Repository": "https://github.com/dolfi/dolfi-python-sdk"
    },
    "split_keywords": [
        "dolfi",
        " api",
        " sdk",
        " search",
        " web scraping",
        " scraping",
        " web",
        " content extraction",
        " ai search",
        " natural language search"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "d817e3f38f6838fdad04c9136202e3dcd42de91054b40edcb8426110d9739008",
                "md5": "0957b4a1c7e720ceffd25626d5f1834d",
                "sha256": "8b14acf72f70722e1cc708c8b58744da14c25cc7c768618c62dd8d394b73b86a"
            },
            "downloads": -1,
            "filename": "dolfi_python_sdk-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0957b4a1c7e720ceffd25626d5f1834d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 13590,
            "upload_time": "2025-08-19T04:13:31",
            "upload_time_iso_8601": "2025-08-19T04:13:31.491406Z",
            "url": "https://files.pythonhosted.org/packages/d8/17/e3f38f6838fdad04c9136202e3dcd42de91054b40edcb8426110d9739008/dolfi_python_sdk-1.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "c05b630b8c4f73a9372db43e79b99fe3812405844affc78f20edb93ed01c9f4d",
                "md5": "6e64e8702927719fd2b3c78b25dbbc34",
                "sha256": "bee2aa358ba795326e89884c6704b253eef9c67075050e651f0e65e334c56063"
            },
            "downloads": -1,
            "filename": "dolfi_python_sdk-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "6e64e8702927719fd2b3c78b25dbbc34",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 13410,
            "upload_time": "2025-08-19T04:13:32",
            "upload_time_iso_8601": "2025-08-19T04:13:32.804268Z",
            "url": "https://files.pythonhosted.org/packages/c0/5b/630b8c4f73a9372db43e79b99fe3812405844affc78f20edb93ed01c9f4d/dolfi_python_sdk-1.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-19 04:13:32",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "dolfi",
    "github_project": "dolfi-python-sdk",
    "github_not_found": true,
    "lcname": "dolfi-python-sdk"
}