blopus 0.1.0__tar.gz

blopus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blopus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blopus-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: blopus
+Version: 0.1.0
+Summary: Official Python SDK for the Blopus web search + fetch API.
+Author: Blopus
+License: MIT
+Project-URL: Homepage, https://blopus.ai
+Project-URL: Documentation, https://docs.blopus.ai
+Project-URL: Source, https://github.com/blopus-ai/blopus-python
+Keywords: blopus,search,web-search,fetch,api,sdk,agents,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.23
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1; extra == "crewai"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: respx>=0.20; extra == "dev"
+Dynamic: license-file
+
+# blopus — Python SDK
+
+Official Python client for the [Blopus](https://blopus.ai) web search + fetch API.
+Blopus is a cheap, fast web-search API backed by an owned index — built for bots
+and agents.
+
+The SDK talks to exactly two data-plane endpoints: `POST /v1/search` and
+`POST /v1/fetch` on `https://api.blopus.ai`.
+
+## Install
+
+```bash
+pip install blopus
+```
+
+Optional framework adapters:
+
+```bash
+pip install "blopus[langchain]"     # blopus.langchain.BlopusSearch
+pip install "blopus[llamaindex]"    # blopus.llamaindex.BlopusToolSpec
+pip install "blopus[crewai]"        # blopus.crewai.BlopusSearchTool
+```
+
+## Authentication
+
+Pass an API key (`blp_live_...`) directly, or set `BLOPUS_API_KEY`:
+
+```bash
+export BLOPUS_API_KEY="blp_live_xxx"
+```
+
+## Quickstart
+
+```python
+from blopus import Blopus
+
+client = Blopus()  # reads BLOPUS_API_KEY
+
+res = client.search("who won the game last night", count=5, freshness="pd")
+for hit in res:
+    print(hit.score, hit.title, hit.url)
+print("remaining quota:", res.remaining_quota)
+
+# Fetch indexed page content
+doc = client.fetch("https://example.com/article")
+print(doc.title, len(doc.content))
+```
+
+### Async
+
+```python
+import asyncio
+from blopus import AsyncBlopus
+
+async def main():
+    async with AsyncBlopus() as client:
+        res = await client.search("openai news", freshness="pw")
+        docs = await client.fetch([r.url for r in res])  # batch fetch
+        print(docs.count, "fetched,", len(docs.failed_results), "missing")
+
+asyncio.run(main())
+```
+
+## `search(...)`
+
+```python
+client.search(
+    query,
+    count=10,                 # 1..50
+    freshness="all",          # pd | pw | pm | p3m | p1y | all
+    include_domains=None,     # ["techcrunch.com", ...]
+    exclude_domains=None,
+    start_date=None,          # "YYYY-MM-DD" or epoch seconds
+    end_date=None,
+    language=None,            # "en", "pt", ...
+    offset=0,                 # pagination, up to 200
+    include_excerpt=False,    # opt in to longer excerpts
+    excerpt_chars=None,       # up to 1200
+)
+```
+
+Returns a `SearchResponse` (iterable over `SearchResult`):
+
+```python
+res.query            # echoed query
+res.results          # list[SearchResult]
+res.count            # number of results returned
+res.offset
+res.more_results     # bool — more pages available
+res.remaining_quota  # int — your remaining monthly units
+
+# SearchResult fields:
+# title, url, snippet, domain, site_name, favicon,
+# published_at, age_seconds, language, score
+```
+
+Search always costs **1 credit**, regardless of parameters or excerpt size.
+
+## `fetch(url_or_urls)`
+
+```python
+# single URL -> FetchResult
+doc = client.fetch("https://example.com/a")
+doc.url, doc.canonical_url, doc.title, doc.content, doc.domain, doc.published_at, doc.language, doc.found
+
+# list of URLs -> BatchFetchResponse
+batch = client.fetch(["https://a.com", "https://b.com"])
+batch.results          # list[FetchResult] that were found
+batch.failed_results   # list[FetchFailure] (url, found=False)
+batch.count            # number found (== credits billed)
+batch.remaining_quota
+```
+
+Batches over the server cap of **50 URLs** are automatically split into ≤50-URL
+calls, run sequentially with a small delay, and merged for you. Fetch bills per
+document found.
+
+## Errors
+
+All errors subclass `blopus.BlopusError`:
+
+| Exception            | When                                   |
+|----------------------|----------------------------------------|
+| `AuthError`          | 401 / 403 — bad, missing or revoked key |
+| `QuotaError`         | 402 — monthly quota exhausted           |
+| `RateLimitError`     | 429 — slow down (`.retry_after`)        |
+| `NotFoundError`      | 404 — no indexed content for a URL      |
+| `BadRequestError`    | 400 / 413 — malformed / too large       |
+| `ServerError`        | 5xx — gateway/backend problem           |
+| `APIConnectionError` | network failure (no response)           |
+
+Requests to `429`/`5xx`/connection errors are retried with exponential backoff
+(honoring `Retry-After`); tune with `Blopus(max_retries=...)`.
+
+## MCP
+
+Blopus also exposes a hosted MCP server (`search` + `fetch` tools) at
+`https://mcp.blopus.ai`, using the same Bearer auth.
+
+```python
+from blopus import mcp_config, print_mcp_config
+print_mcp_config()        # prints the mcpServers JSON to paste into your MCP client
+cfg = mcp_config()        # or get it as a dict
+```
+
+## CLI
+
+```bash
+blopus search "who won the game" --count 5 --freshness pd
+blopus search "openai" --include-domains techcrunch.com,theverge.com --json
+blopus fetch https://example.com/a https://example.com/b
+blopus mcp-config
+```
+
+## License
+
+MIT

blopus-0.1.0/README.md

@@ -0,0 +1,157 @@
+# blopus — Python SDK
+
+Official Python client for the [Blopus](https://blopus.ai) web search + fetch API.
+Blopus is a cheap, fast web-search API backed by an owned index — built for bots
+and agents.
+
+The SDK talks to exactly two data-plane endpoints: `POST /v1/search` and
+`POST /v1/fetch` on `https://api.blopus.ai`.
+
+## Install
+
+```bash
+pip install blopus
+```
+
+Optional framework adapters:
+
+```bash
+pip install "blopus[langchain]"     # blopus.langchain.BlopusSearch
+pip install "blopus[llamaindex]"    # blopus.llamaindex.BlopusToolSpec
+pip install "blopus[crewai]"        # blopus.crewai.BlopusSearchTool
+```
+
+## Authentication
+
+Pass an API key (`blp_live_...`) directly, or set `BLOPUS_API_KEY`:
+
+```bash
+export BLOPUS_API_KEY="blp_live_xxx"
+```
+
+## Quickstart
+
+```python
+from blopus import Blopus
+
+client = Blopus()  # reads BLOPUS_API_KEY
+
+res = client.search("who won the game last night", count=5, freshness="pd")
+for hit in res:
+    print(hit.score, hit.title, hit.url)
+print("remaining quota:", res.remaining_quota)
+
+# Fetch indexed page content
+doc = client.fetch("https://example.com/article")
+print(doc.title, len(doc.content))
+```
+
+### Async
+
+```python
+import asyncio
+from blopus import AsyncBlopus
+
+async def main():
+    async with AsyncBlopus() as client:
+        res = await client.search("openai news", freshness="pw")
+        docs = await client.fetch([r.url for r in res])  # batch fetch
+        print(docs.count, "fetched,", len(docs.failed_results), "missing")
+
+asyncio.run(main())
+```
+
+## `search(...)`
+
+```python
+client.search(
+    query,
+    count=10,                 # 1..50
+    freshness="all",          # pd | pw | pm | p3m | p1y | all
+    include_domains=None,     # ["techcrunch.com", ...]
+    exclude_domains=None,
+    start_date=None,          # "YYYY-MM-DD" or epoch seconds
+    end_date=None,
+    language=None,            # "en", "pt", ...
+    offset=0,                 # pagination, up to 200
+    include_excerpt=False,    # opt in to longer excerpts
+    excerpt_chars=None,       # up to 1200
+)
+```
+
+Returns a `SearchResponse` (iterable over `SearchResult`):
+
+```python
+res.query            # echoed query
+res.results          # list[SearchResult]
+res.count            # number of results returned
+res.offset
+res.more_results     # bool — more pages available
+res.remaining_quota  # int — your remaining monthly units
+
+# SearchResult fields:
+# title, url, snippet, domain, site_name, favicon,
+# published_at, age_seconds, language, score
+```
+
+Search always costs **1 credit**, regardless of parameters or excerpt size.
+
+## `fetch(url_or_urls)`
+
+```python
+# single URL -> FetchResult
+doc = client.fetch("https://example.com/a")
+doc.url, doc.canonical_url, doc.title, doc.content, doc.domain, doc.published_at, doc.language, doc.found
+
+# list of URLs -> BatchFetchResponse
+batch = client.fetch(["https://a.com", "https://b.com"])
+batch.results          # list[FetchResult] that were found
+batch.failed_results   # list[FetchFailure] (url, found=False)
+batch.count            # number found (== credits billed)
+batch.remaining_quota
+```
+
+Batches over the server cap of **50 URLs** are automatically split into ≤50-URL
+calls, run sequentially with a small delay, and merged for you. Fetch bills per
+document found.
+
+## Errors
+
+All errors subclass `blopus.BlopusError`:
+
+| Exception            | When                                   |
+|----------------------|----------------------------------------|
+| `AuthError`          | 401 / 403 — bad, missing or revoked key |
+| `QuotaError`         | 402 — monthly quota exhausted           |
+| `RateLimitError`     | 429 — slow down (`.retry_after`)        |
+| `NotFoundError`      | 404 — no indexed content for a URL      |
+| `BadRequestError`    | 400 / 413 — malformed / too large       |
+| `ServerError`        | 5xx — gateway/backend problem           |
+| `APIConnectionError` | network failure (no response)           |
+
+Requests to `429`/`5xx`/connection errors are retried with exponential backoff
+(honoring `Retry-After`); tune with `Blopus(max_retries=...)`.
+
+## MCP
+
+Blopus also exposes a hosted MCP server (`search` + `fetch` tools) at
+`https://mcp.blopus.ai`, using the same Bearer auth.
+
+```python
+from blopus import mcp_config, print_mcp_config
+print_mcp_config()        # prints the mcpServers JSON to paste into your MCP client
+cfg = mcp_config()        # or get it as a dict
+```
+
+## CLI
+
+```bash
+blopus search "who won the game" --count 5 --freshness pd
+blopus search "openai" --include-domains techcrunch.com,theverge.com --json
+blopus fetch https://example.com/a https://example.com/b
+blopus mcp-config
+```
+
+## License
+
+MIT

blopus-0.1.0/blopus/__init__.py

@@ -0,0 +1,61 @@
+"""Blopus — official Python SDK for the Blopus web search + fetch API.
+
+Quickstart::
+
+    from blopus import Blopus
+
+    client = Blopus(api_key="blp_live_...")   # or set BLOPUS_API_KEY
+    for hit in client.search("latest ai news", freshness="pd"):
+        print(hit.title, hit.url)
+
+    doc = client.fetch("https://example.com/article")
+
+The SDK calls only two data-plane endpoints — ``POST /v1/search`` and
+``POST /v1/fetch`` on https://api.blopus.ai.
+"""
+from __future__ import annotations
+
+from ._async import AsyncBlopus
+from ._version import __version__
+from .client import Blopus
+from .exceptions import (
+    APIConnectionError,
+    AuthError,
+    BadRequestError,
+    BlopusError,
+    NotFoundError,
+    QuotaError,
+    RateLimitError,
+    ServerError,
+)
+from .mcp import mcp_config, print_mcp_config
+from .models import (
+    BatchFetchResponse,
+    FetchFailure,
+    FetchResult,
+    SearchResponse,
+    SearchResult,
+)
+
+__all__ = [
+    "__version__",
+    "Blopus",
+    "AsyncBlopus",
+    "mcp_config",
+    "print_mcp_config",
+    # models
+    "SearchResponse",
+    "SearchResult",
+    "FetchResult",
+    "FetchFailure",
+    "BatchFetchResponse",
+    # exceptions
+    "BlopusError",
+    "APIConnectionError",
+    "AuthError",
+    "BadRequestError",
+    "NotFoundError",
+    "RateLimitError",
+    "QuotaError",
+    "ServerError",
+]

blopus-0.1.0/blopus/_async.py

@@ -0,0 +1,139 @@
+"""Asynchronous Blopus client (httpx.AsyncClient). Mirrors :class:`Blopus` exactly.
+
+    import asyncio
+    from blopus import AsyncBlopus
+
+    async def main():
+        async with AsyncBlopus() as client:
+            res = await client.search("openai news", freshness="pw")
+            docs = await client.fetch([r.url for r in res])
+
+    asyncio.run(main())
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Optional, Sequence, Union
+
+import httpx
+
+from . import _common as C
+from .exceptions import APIConnectionError
+from .models import BatchFetchResponse, FetchFailure, FetchResult, SearchResponse
+
+
+class AsyncBlopus:
+    """Async client for the Blopus search + fetch API. Same surface as :class:`Blopus`."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = C.DEFAULT_TIMEOUT,
+        max_retries: int = C.DEFAULT_MAX_RETRIES,
+        chunk_delay: float = C.DEFAULT_CHUNK_DELAY,
+        user_agent: str = C.USER_AGENT,
+    ) -> None:
+        self._api_key = C.resolve_api_key(api_key)
+        self.base_url = C.resolve_base_url(base_url)
+        self.max_retries = max_retries
+        self.chunk_delay = chunk_delay
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=C.build_headers(self._api_key, user_agent),
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncBlopus":
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.aclose()
+
+    async def _post(self, path: str, body: dict) -> dict:
+        attempt = 0
+        while True:
+            status: Optional[int] = None
+            retry_after: Optional[int] = None
+            try:
+                resp = await self._http.post(path, json=body)
+                status = resp.status_code
+                retry_after = C.parse_retry_after(resp.headers.get("Retry-After"))
+                if 200 <= status < 300:
+                    return C.parse_json_or_raise(status, resp.text, retry_after)
+            except httpx.HTTPError as exc:
+                if not C.should_retry(None, attempt, self.max_retries):
+                    raise APIConnectionError(f"Request failed: {exc}") from exc
+                await asyncio.sleep(C.backoff_seconds(attempt, None))
+                attempt += 1
+                continue
+
+            if C.should_retry(status, attempt, self.max_retries):
+                await asyncio.sleep(C.backoff_seconds(attempt, retry_after))
+                attempt += 1
+                continue
+            return C.parse_json_or_raise(status, resp.text, retry_after)
+
+    async def search(
+        self,
+        query: str,
+        *,
+        count: int = 10,
+        freshness: str = "all",
+        include_domains: Optional[Sequence[str]] = None,
+        exclude_domains: Optional[Sequence[str]] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        language: Optional[str] = None,
+        offset: int = 0,
+        include_excerpt: bool = False,
+        excerpt_chars: Optional[int] = None,
+    ) -> SearchResponse:
+        body = C.build_search_body(
+            query,
+            count=count,
+            freshness=freshness,
+            include_domains=include_domains,
+            exclude_domains=exclude_domains,
+            start_date=start_date,
+            end_date=end_date,
+            language=language,
+            offset=offset,
+            include_excerpt=include_excerpt,
+            excerpt_chars=excerpt_chars,
+        )
+        return SearchResponse.from_dict(await self._post("/v1/search", body))
+
+    async def fetch(
+        self, url_or_urls: Union[str, Sequence[str]]
+    ) -> Union[FetchResult, BatchFetchResponse]:
+        is_batch, urls, single = C.normalize_fetch_urls(url_or_urls)
+        if not is_batch:
+            data = await self._post("/v1/fetch", {"url": single})
+            return FetchResult.from_dict(data)
+        return await self._fetch_batch(urls)
+
+    async def _fetch_batch(self, urls: Sequence[str]) -> BatchFetchResponse:
+        chunks = C.chunk_urls(urls)
+        merged_results: list[FetchResult] = []
+        merged_failed: list[FetchFailure] = []
+        remaining: Optional[int] = None
+        for i, chunk in enumerate(chunks):
+            if i > 0 and self.chunk_delay > 0:
+                await asyncio.sleep(self.chunk_delay)
+            data = await self._post("/v1/fetch", {"urls": list(chunk)})
+            part = BatchFetchResponse.from_dict(data)
+            merged_results.extend(part.results)
+            merged_failed.extend(part.failed_results)
+            if part.remaining_quota is not None:
+                remaining = part.remaining_quota
+        return BatchFetchResponse(
+            results=merged_results,
+            failed_results=merged_failed,
+            count=len(merged_results),
+            remaining_quota=remaining,
+        )