Metadata-Version: 2.3
Name: gl-smart-search-sdk
Version: 0.0.14b2
Summary: SDK for GL Smart Search API backend
Author: GL Smart Search Team
Author-email: smartsearch@gdplabs.id
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: click (>=8.2.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: httpx_sse (>=0.4.3,<0.5.0)
Requires-Dist: pydantic (>=2.10.0)
Requires-Dist: python-dotenv (>=1.0.0)
Requires-Dist: requests
Requires-Dist: rich (>=13.0.0)
Requires-Dist: websockets (>=15.0.1,<16.0.0)
Description-Content-Type: text/markdown

<p align="center">
  🔍 GL Smart Search SDK 🐍
</p>

<p align="center">
    <a href="https://pypi.org/project/gl-smart-search-sdk/"><img src="https://img.shields.io/pypi/v/gl-smart-search-sdk" alt="PyPI Latest Release"></a>
    <a href="https://github.com/GDP-ADMIN/smart-search-sdk/blob/main/python/gl-smart-search-sdk/LICENSE"><img src="https://img.shields.io/pypi/l/gl-smart-search-sdk" alt="License"></a>
</p>

Python SDK for **GL Smart Search v2**: **web search** and **connector** integrations (GitHub, Google Drive, Gmail, Google Calendar).

> **v1 clients** (`search`, `deep_research`, authentication email modules) are not included in this package. Use the legacy **`smart-search-sdk`** PyPI artifact if you still depend on v1.

## Requirements

- Python **3.11+** (tested on 3.11–3.13)

## Installation

```bash
pip install gl-smart-search-sdk
```

GDP Labs internal registry:

```bash
pip install gl-smart-search-sdk --index-url https://glsdk.gdplabs.id/gen-ai-internal/simple/
```

## Quick start — Web Search

```python
import asyncio
import os

from gl_smart_search_sdk.web.client import WebSearchClient
from gl_smart_search_sdk.web.models import GetWebSearchResultsRequest


async def main() -> None:
    client = WebSearchClient(base_url=os.environ["GL_SMARTSEARCH_BASE_URL"])
    await client.authenticate(token=os.environ["GL_SMARTSEARCH_TOKEN"])

    request = GetWebSearchResultsRequest(
        query="What is retrieval-augmented generation?",
        result_type="snippets",
        size=5,
    )
    response = await client.search_web(request)
    print(response)


asyncio.run(main())
```

## Quick start — Connectors

```python
import asyncio
import os

from gl_smart_search_sdk.connector.client import ConnectorClient
from gl_smart_search_sdk.connector.models import AppName, ConnectorRequest


async def main() -> None:
    client = ConnectorClient(base_url=os.environ["GL_SMARTSEARCH_BASE_URL"])
    await client.authenticate(token=os.environ["GL_SMARTSEARCH_TOKEN"])

    request = ConnectorRequest(query="meetings next week")
    response = await client.search_connector(
        app_name=AppName.GOOGLE_CALENDAR,
        gl_token=os.environ["GL_CONNECTORS_USER_TOKEN"],
        request=request,
    )
    print(response)


asyncio.run(main())
```

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GL_SMARTSEARCH_BASE_URL` | Yes | API base URL |
| `GL_SMARTSEARCH_TOKEN` | Yes* | Bearer token for API calls |
| `GL_SMARTSEARCH_USER_IDENTIFIER` | CLI | User id (CLI / credential flows) |
| `GL_SMARTSEARCH_USER_SECRET` | CLI | User secret (CLI / credential flows) |
| `GL_CONNECTORS_USER_TOKEN` | Connectors | GL Connectors user token |
| `GL_CONNECTORS_DEFAULT_CALLBACK_URL` | Connectors | OAuth callback URL (optional) |

\* Required for SDK clients unless passed explicitly to `authenticate()`.

Load variables with `python-dotenv` or your platform’s secret manager before creating clients.

## CLI

The package includes the **`gl-smart-search`** CLI (web and connector subcommands).

```bash
poetry run gl-smart-search --help
poetry run gl-smart-search status
```

See [gl_smart_search_sdk/cli/README.md](gl_smart_search_sdk/cli/README.md) for full command reference.

## Examples

Non-interactive scripts live in the repository under `python/examples/`:

- `web_search.py` — web search, URLs, fetch, snippets, keypoints
- `connector_search.py` — connector search and management

## API overview (v2)

### `WebSearchClient`

- `search_web` — search with snippets, keypoints, or summary
- `search_web_urls` — return relevant URLs
- `search_web_map` — site map for a base URL
- `fetch_web_page` — fetch page content
- `get_web_page_snippets` — snippets from a URL
- `get_web_page_keypoints` — key points from a URL

### `ConnectorClient`

- `search_connector` — search a connected app
- `connect_connector` — start connector OAuth flow
- `disconnect_connector` — remove connector integration

All clients extend **`BaseGLSmartSearchClient`** (authentication, HTTP, streaming helpers).

## Documentation

- [GL Smart Search Gitbook](https://gdplabs.gitbook.io/smart-search)
- [HTTP API docs](https://search-api.gdplabs.id/docs)
- Repository root [README](../../README.md) and [CHANGELOG](../../CHANGELOG.md)

## Development

```bash
cd python/gl-smart-search-sdk
poetry install
poetry run pytest
poetry run gl-smart-search --version
```

