Metadata-Version: 2.4
Name: openserp
Version: 0.1.1
Summary: Python SDK for the OpenSERP self-hosted server and OpenSERP Cloud.
Project-URL: Homepage, https://openserp.org
Project-URL: Documentation, https://openserp.org/docs
Project-URL: Repository, https://github.com/karust/openserp_project
Project-URL: Issues, https://github.com/karust/openserp_project/issues
Project-URL: Changelog, https://github.com/karust/openserp_project/releases?q=sdk-python
Project-URL: Source Code, https://github.com/karust/openserp_project/tree/master/integrations/sdk-python
Project-URL: Chat (Telegram), https://t.me/openserp_cloud
Author: OpenSERP
License-Expression: MIT
Keywords: ai-grounding,baidu,bing,duckduckgo,ecosia,google,openserp,search,seo,serp,yandex
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# OpenSERP Python SDK

Alpha: API may change before 1.0.

Python SDK for the OpenSERP self-hosted server and OpenSERP Cloud. The same client works against both backends.

## Install

```bash
pip install openserp
```

For DataFrame export:

```bash
pip install "openserp[pandas]"
```

## OSS Mode

OSS mode is the default. Run the open source server locally, then point the SDK at it:

```python
from openserp import OpenSERP

client = OpenSERP(base_url="http://localhost:7000")

resp = client.search(
    engine="google",
    text="openserp",
    limit=10,
    region="US",
)

print(resp.results[0].title, resp.results[0].url)
```

If you omit every option, the client uses `http://localhost:7000`.

## Cloud Mode

Pass an API key and the client defaults to `https://api.openserp.org/v1`.

```python
import os

from openserp import OpenSERP

client = OpenSERP(api_key=os.environ["OPENSERP_API_KEY"])
resp = client.search(engine="google", text="openserp")

print(resp.results[0].title)
print(client.last_response.credits)
```

## Async

```python
import asyncio
import os

from openserp import AsyncOpenSERP


async def main() -> None:
    async with AsyncOpenSERP(api_key=os.environ["OPENSERP_API_KEY"]) as client:
        resp = await client.search(engine="google", text="openserp")
        print(resp.results[0].title)


asyncio.run(main())
```

## Mega Search

```python
from openserp import OpenSERP

client = OpenSERP()

mega = client.mega_search(
    text="openserp",
    engines=["google", "bing", "yandex"],
    mode="balanced",
)

df = mega.to_pandas()
print(df[["rank", "title", "url", "engine"]])
```

Convenience helpers are also available:

```python
client.fast_search(text="openserp", engines=["google", "bing"])
client.any_search(text="openserp", engines=["google", "bing"])
client.mega_image(text="golang logo", engines=["google", "bing"])
```

## AI / RAG

```python
from openserp import OpenSERP

client = OpenSERP()
resp = client.search(engine="google", text="latest postgres indexing guide", limit=5)

context = "\n\n".join(
    f"{item.title}\n{item.url}\n{item.snippet}"
    for item in resp.results
)

prompt = f"Use these web results as grounding:\n\n{context}\n\nSummarize the key points."
```

## SEO Keyword Tracker

```python
from openserp import OpenSERP

client = OpenSERP()
keywords = ["openserp", "serp api", "google search api"]
frames = []

for keyword in keywords:
    resp = client.search(engine="google", text=keyword, region="US", limit=10)
    frame = resp.to_pandas()
    frame["keyword"] = keyword
    frames.append(frame)

report = __import__("pandas").concat(frames, ignore_index=True)
report.to_csv("rank-report.csv", index=False)
```

## Async Batch

```python
import asyncio

from openserp import AsyncOpenSERP


async def main() -> None:
    sem = asyncio.Semaphore(20)
    queries = [f"keyword {i}" for i in range(500)]

    async with AsyncOpenSERP() as client:
        async def run(query: str):
            async with sem:
                return await client.search(engine="google", text=query, limit=10)

        responses = await asyncio.gather(*(run(query) for query in queries))
        print(len(responses))


asyncio.run(main())
```

## Endpoint Availability

Search endpoints work in both modes. Operational OSS endpoints such as `health()`, `stats()`, `parse_google()`, and `parse_bing()` require a self-hosted server and raise `OssOnlyError` in Cloud mode.

Cloud account endpoints such as `me()`, `pricing()`, `engines_status()`, and `engines_capabilities()` require Cloud mode and raise `CloudOnlyError` in OSS mode.

## Development

```bash
python -m pip install -e ".[dev,pandas]"
pytest
ruff check .
mypy src
python -m build
```

The project is scaffolded for `uv` too:

```bash
uv build
```
