openserp 0.1.0__tar.gz

openserp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.venv-*/
+__pycache__/
+dist/
+*.egg-info/

openserp-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: openserp
+Version: 0.1.0
+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-URL: Issues, https://github.com/karust/openserp/issues
+Author: OpenSERP
+License-Expression: MIT
+Keywords: ai-grounding,baidu,bing,duckduckgo,ecosia,google,openserp,search,seo,serp,yandex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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: 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
+```

openserp-0.1.0/README.md

@@ -0,0 +1,178 @@
+# 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
+```

openserp-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openserp"
+version = "0.1.0"
+description = "Python SDK for the OpenSERP self-hosted server and OpenSERP Cloud."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "OpenSERP" }]
+keywords = [
+  "openserp",
+  "serp",
+  "search",
+  "google",
+  "bing",
+  "yandex",
+  "baidu",
+  "duckduckgo",
+  "ecosia",
+  "seo",
+  "ai-grounding",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.7,<3",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.0"]
+dev = [
+  "build>=1.2",
+  "mypy>=1.10",
+  "pytest>=8.2",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://openserp.org"
+Documentation = "https://openserp.org/docs"
+Repository = "https://github.com/karust/openserp"
+Issues = "https://github.com/karust/openserp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openserp"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unreachable = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

openserp-0.1.0/src/openserp/__init__.py

@@ -0,0 +1,66 @@
+from .client import AsyncOpenSERP, OpenSERP
+from .errors import (
+    CaptchaError,
+    CloudOnlyError,
+    OssOnlyError,
+    RateLimitError,
+    SERPError,
+    TimeoutError,
+)
+from .models import (
+    Backend,
+    CircuitBreakerStatsResponse,
+    CloudAccount,
+    CreditInfo,
+    Engine,
+    EnginesCapabilities,
+    EnginesStatus,
+    HealthStatus,
+    ImageEnvelope,
+    ImageResult,
+    LastResponse,
+    MegaEnginesResponse,
+    MegaMode,
+    MegaSearchEnvelope,
+    Pricing,
+    ProxyStats,
+    ReadinessStatus,
+    ResponseFormat,
+    SearchEnvelope,
+    SearchResult,
+    StatsResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncOpenSERP",
+    "Backend",
+    "CaptchaError",
+    "CircuitBreakerStatsResponse",
+    "CloudAccount",
+    "CloudOnlyError",
+    "CreditInfo",
+    "Engine",
+    "EnginesCapabilities",
+    "EnginesStatus",
+    "HealthStatus",
+    "ImageEnvelope",
+    "ImageResult",
+    "LastResponse",
+    "MegaEnginesResponse",
+    "MegaMode",
+    "MegaSearchEnvelope",
+    "OpenSERP",
+    "OssOnlyError",
+    "Pricing",
+    "ProxyStats",
+    "RateLimitError",
+    "ReadinessStatus",
+    "ResponseFormat",
+    "SERPError",
+    "SearchEnvelope",
+    "SearchResult",
+    "StatsResponse",
+    "TimeoutError",
+]

openserp-0.1.0/src/openserp/backend.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from .models import Backend
+
+OSS_BASE_URL = "http://localhost:7000"
+CLOUD_BASE_URL = "https://api.openserp.org/v1"
+
+
+def normalize_base_url(base_url: str) -> str:
+    return base_url.rstrip("/")
+
+
+def resolve_base_url(api_key: str | None = None, base_url: str | None = None) -> str:
+    if base_url:
+        return normalize_base_url(base_url)
+    if api_key:
+        return CLOUD_BASE_URL
+    return OSS_BASE_URL
+
+
+def infer_backend(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    backend: Backend | None = None,
+) -> Backend:
+    if backend:
+        return backend
+
+    if base_url:
+        try:
+            if urlparse(base_url).hostname == "api.openserp.org":
+                return "cloud"
+        except ValueError:
+            if "api.openserp.org" in base_url:
+                return "cloud"
+
+    if api_key:
+        return "cloud"
+
+    return "oss"