brime 0.1.0__py3-none-any.whl

brime/__init__.py

@@ -0,0 +1,58 @@
+"""Brime — Official Python SDK."""
+
+from brime._version import __version__
+from brime.client import Brime
+from brime.errors import (
+    AuthenticationError,
+    BrimeError,
+    InsufficientCreditsError,
+    InternalError,
+    InvalidRequestError,
+    NotFoundError,
+    RateLimitError,
+    UpstreamError,
+)
+from brime.models.extract import (
+    ExtractFailedItem,
+    ExtractMetadata,
+    ExtractResponse,
+    ExtractResultItem,
+)
+from brime.models.research import (
+    ResearchBasicResponse,
+    ResearchDeepInitResponse,
+    ResearchSseEvent,
+    ResearchStatusResponse,
+)
+from brime.models.search import SearchResponse, SearchResultItem
+
+__all__ = [
+    "__version__",
+    "Brime",
+    "BrimeError",
+    "AuthenticationError",
+    "RateLimitError",
+    "InsufficientCreditsError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "UpstreamError",
+    "InternalError",
+    "SearchResponse",
+    "SearchResultItem",
+    "ExtractResponse",
+    "ExtractResultItem",
+    "ExtractFailedItem",
+    "ExtractMetadata",
+    "ResearchBasicResponse",
+    "ResearchDeepInitResponse",
+    "ResearchStatusResponse",
+    "ResearchSseEvent",
+]
+
+
+def __getattr__(name: str) -> object:  # pragma: no cover
+    """Lazy AsyncBrime import (added in S6)."""
+    if name == "AsyncBrime":
+        from brime.async_client import AsyncBrime
+        return AsyncBrime
+    raise AttributeError(name)

brime/_http.py

@@ -0,0 +1,99 @@
+"""Internal HTTP layer shared by sync and async clients.
+
+Responsibilities:
+    - Resolve api_key (arg → env BRIME_API_KEY)
+    - Resolve base_url (arg → env BRIME_BASE_URL → https://api.brime.dev)
+    - Build standard headers (Authorization, User-Agent, optional Idempotency-Key)
+    - Decode error responses into Brime exceptions
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from typing import Any, Dict, Mapping, Optional
+
+import httpx
+
+from brime._version import __version__
+from brime.errors import BrimeError, exception_from_response
+
+DEFAULT_BASE_URL = "https://api.brime.dev"
+DEFAULT_TIMEOUT_S = 30.0
+DEEP_RESEARCH_TIMEOUT_S = 600.0
+USER_AGENT = f"brime-python/{__version__}"
+
+
+def resolve_api_key(api_key: Optional[str]) -> str:
+    if api_key:
+        return api_key
+    env = os.environ.get("BRIME_API_KEY")
+    if env:
+        return env
+    raise RuntimeError(
+        "Brime API key not set. Pass api_key=... or set BRIME_API_KEY env var."
+    )
+
+
+def resolve_base_url(base_url: Optional[str]) -> str:
+    if base_url:
+        return base_url.rstrip("/")
+    env = os.environ.get("BRIME_BASE_URL")
+    if env:
+        return env.rstrip("/")
+    return DEFAULT_BASE_URL
+
+
+def build_headers(
+    api_key: str,
+    *,
+    json_body: bool = True,
+    idempotency_key: Optional[str] = None,
+    accept: Optional[str] = None,
+    extra: Optional[Mapping[str, str]] = None,
+) -> Dict[str, str]:
+    headers: Dict[str, str] = {
+        "authorization": f"Bearer {api_key}",
+        "user-agent": USER_AGENT,
+        "accept": accept or "application/json",
+    }
+    if json_body:
+        headers["content-type"] = "application/json"
+    if idempotency_key:
+        headers["idempotency-key"] = idempotency_key
+    if extra:
+        for k, v in extra.items():
+            headers[k.lower()] = v
+    return headers
+
+
+def new_idempotency_key() -> str:
+    return str(uuid.uuid4())
+
+
+def decode_response(res: httpx.Response) -> Any:
+    """Parse JSON or raise the appropriate BrimeError on non-2xx."""
+    text = res.text
+    body: Any = None
+    if text:
+        try:
+            body = json.loads(text)
+        except json.JSONDecodeError:
+            body = None
+
+    request_id_header = res.headers.get("x-request-id")
+
+    if res.is_success:
+        return body
+
+    err_body = body if isinstance(body, dict) else None
+    raise exception_from_response(res.status_code, err_body, request_id_header)
+
+
+def wrap_transport_error(exc: Exception) -> BrimeError:
+    """Convert httpx transport-level errors to a BrimeError shape."""
+    return exception_from_response(
+        0,
+        {"error": {"code": "internal_error", "message": f"network error: {exc!s}"}},
+    )

brime/_polling.py

@@ -0,0 +1,72 @@
+"""Research deep-mode polling helpers.
+
+`research(depth="deep", wait=True)` blocks until the job reaches a
+terminal state (complete | errored | timeout) or `poll_timeout` elapses.
+
+Design:
+    - Caller passes a status fetcher (sync or async closure)
+    - We delay between polls with optional jitter-free exponential backoff
+      capped at `max_interval`
+    - Terminal states stop polling; on poll_timeout we raise TimeoutError
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Awaitable, Callable
+
+from brime.models.research import ResearchStatusResponse
+
+TERMINAL = ("complete", "errored", "timeout")
+
+
+def _next_interval(prev: float, max_interval: float) -> float:
+    return min(prev * 1.5, max_interval)
+
+
+def poll_until_terminal_sync(
+    fetch: Callable[[], ResearchStatusResponse],
+    *,
+    initial_interval: float,
+    max_interval: float,
+    poll_timeout: float,
+) -> ResearchStatusResponse:
+    deadline = time.monotonic() + poll_timeout
+    interval = initial_interval
+    while True:
+        status = fetch()
+        if status.status in TERMINAL:
+            return status
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise TimeoutError(
+                f"research polling exceeded {poll_timeout}s "
+                f"(last status: {status.status}, round {status.current_round}/{status.max_rounds})"
+            )
+        time.sleep(min(interval, remaining))
+        interval = _next_interval(interval, max_interval)
+
+
+async def poll_until_terminal_async(
+    fetch: Callable[[], Awaitable[ResearchStatusResponse]],
+    *,
+    initial_interval: float,
+    max_interval: float,
+    poll_timeout: float,
+) -> ResearchStatusResponse:
+    loop = asyncio.get_event_loop()
+    deadline = loop.time() + poll_timeout
+    interval = initial_interval
+    while True:
+        status = await fetch()
+        if status.status in TERMINAL:
+            return status
+        remaining = deadline - loop.time()
+        if remaining <= 0:
+            raise TimeoutError(
+                f"research polling exceeded {poll_timeout}s "
+                f"(last status: {status.status}, round {status.current_round}/{status.max_rounds})"
+            )
+        await asyncio.sleep(min(interval, remaining))
+        interval = _next_interval(interval, max_interval)

brime/_sse.py

@@ -0,0 +1,131 @@
+"""Server-Sent Events parser.
+
+Brime /v1/research stream emits frames like::
+
+    event: tool_call\\n
+    data: {"round": 1, "queries": ["..."]}\\n
+    \\n
+
+This module turns httpx byte iterators into ResearchSseEvent dicts.
+Handles fragmented chunks (a single SSE frame may arrive across multiple
+read() calls) and the [DONE] terminator.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import AsyncIterator, Dict, Iterator, List, Optional
+
+
+class _SseAccumulator:
+    """Stateful frame buffer.
+
+    Feed `feed(text)` repeatedly with raw decoded chunks. After each feed,
+    drain `pop_frames()` to collect complete SSE frames. A frame is delimited
+    by a blank line (\\n\\n).
+    """
+
+    __slots__ = ("_buf", "_done")
+
+    def __init__(self) -> None:
+        self._buf = ""
+        self._done = False
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    def feed(self, chunk: str) -> None:
+        self._buf += chunk
+
+    def pop_frames(self) -> List[Dict[str, object]]:
+        out: List[Dict[str, object]] = []
+        while True:
+            idx = self._buf.find("\n\n")
+            if idx < 0:
+                break
+            frame = self._buf[:idx]
+            self._buf = self._buf[idx + 2 :]
+            evt = _parse_frame(frame)
+            if evt is None:
+                continue
+            if evt is _DONE_SENTINEL:
+                self._done = True
+                break
+            out.append(evt)
+        return out
+
+
+_DONE_SENTINEL: Dict[str, object] = {"__done__": True}
+
+
+def _parse_frame(frame: str) -> Optional[Dict[str, object]]:
+    """Convert a raw SSE frame text into a normalized event dict.
+
+    Returns None for empty/comment-only frames; returns _DONE_SENTINEL on
+    `data: [DONE]` lines (used by some adapters).
+    """
+    event_type: Optional[str] = None
+    event_id: Optional[str] = None
+    data_lines: List[str] = []
+    for raw_line in frame.split("\n"):
+        line = raw_line.rstrip("\r")
+        if not line or line.startswith(":"):
+            continue
+        if ":" in line:
+            field, _, value = line.partition(":")
+            value = value.lstrip(" ")
+        else:
+            field, value = line, ""
+        if field == "event":
+            event_type = value
+        elif field == "id":
+            event_id = value
+        elif field == "data":
+            data_lines.append(value)
+
+    if not data_lines and event_type is None:
+        return None
+
+    raw_data = "\n".join(data_lines)
+    if raw_data.strip() == "[DONE]":
+        return _DONE_SENTINEL
+
+    parsed: object
+    if raw_data == "":
+        parsed = {}
+    else:
+        try:
+            parsed = json.loads(raw_data)
+        except json.JSONDecodeError:
+            parsed = raw_data  # fall back to raw string payload
+
+    return {
+        "event": event_type or "message",
+        "data": parsed,
+        "id": event_id,
+    }
+
+
+def iter_sse_sync(byte_iter: Iterator[bytes]) -> Iterator[Dict[str, object]]:
+    acc = _SseAccumulator()
+    for chunk in byte_iter:
+        if not chunk:
+            continue
+        acc.feed(chunk.decode("utf-8", errors="replace"))
+        for evt in acc.pop_frames():
+            yield evt
+        if acc.done:
+            return
+
+
+async def iter_sse_async(byte_iter: AsyncIterator[bytes]) -> AsyncIterator[Dict[str, object]]:
+    acc = _SseAccumulator()
+    async for chunk in byte_iter:
+        if not chunk:
+            continue
+        acc.feed(chunk.decode("utf-8", errors="replace"))
+        for evt in acc.pop_frames():
+            yield evt
+        if acc.done:
+            return

brime/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

brime/async_client.py

@@ -0,0 +1,308 @@
+"""Asynchronous Brime client (mirror of brime.client.Brime)."""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, List, Literal, Optional, Union
+
+import httpx
+
+from brime._http import (
+    DEEP_RESEARCH_TIMEOUT_S,
+    DEFAULT_TIMEOUT_S,
+    build_headers,
+    decode_response,
+    new_idempotency_key,
+    resolve_api_key,
+    resolve_base_url,
+    wrap_transport_error,
+)
+from brime._polling import poll_until_terminal_async
+from brime._sse import iter_sse_async
+from brime.errors import BrimeError
+from brime.models.extract import ExtractResponse
+from brime.models.research import (
+    ResearchBasicResponse,
+    ResearchDeepInitResponse,
+    ResearchSseEvent,
+    ResearchStatusResponse,
+)
+from brime.models.search import SearchResponse
+
+
+class AsyncBrime:
+    """Asynchronous Brime API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT_S,
+    ) -> None:
+        self._api_key = resolve_api_key(api_key)
+        self._base_url = resolve_base_url(base_url)
+        self._timeout = timeout
+        self._client = httpx.AsyncClient(base_url=self._base_url, timeout=timeout)
+
+    async def __aenter__(self) -> "AsyncBrime":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    # ── Search ─────────────────────────────────────────────────────────
+
+    async def search(
+        self,
+        query: str,
+        *,
+        depth: Literal["instant", "basic", "advanced"] = "basic",
+        topic: Literal["general", "news", "finance"] = "general",
+        max_results: int = 5,
+        time_range: Optional[Literal["day", "week", "month", "year"]] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        include_answer: Union[bool, Literal["basic", "advanced"]] = True,
+        include_images: bool = False,
+        domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        timeout: Optional[float] = None,
+    ) -> SearchResponse:
+        body: Dict[str, Any] = {
+            "query": query,
+            "depth": depth,
+            "topic": topic,
+            "max_results": max_results,
+            "include_answer": include_answer,
+            "include_images": include_images,
+        }
+        if time_range:
+            body["time_range"] = time_range
+        if start_date:
+            body["start_date"] = start_date
+        if end_date:
+            body["end_date"] = end_date
+        if domains:
+            body["domains"] = domains
+        if exclude_domains:
+            body["exclude_domains"] = exclude_domains
+        data = await self._post_json("/v1/search", body, timeout=timeout)
+        return SearchResponse.model_validate(data)
+
+    # ── Extract ────────────────────────────────────────────────────────
+
+    async def extract(
+        self,
+        urls: Union[str, List[str]],
+        *,
+        include_metadata: bool = False,
+        per_url_timeout_ms: int = 25_000,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> ExtractResponse:
+        url_list = [urls] if isinstance(urls, str) else list(urls)
+        body: Dict[str, Any] = {
+            "urls": url_list,
+            "include_metadata": include_metadata,
+            "per_url_timeout_ms": per_url_timeout_ms,
+        }
+        idem = idempotency_key or new_idempotency_key()
+        data = await self._post_json(
+            "/v1/extract", body, idempotency_key=idem, timeout=timeout
+        )
+        return ExtractResponse.model_validate(data)
+
+    # ── Research ───────────────────────────────────────────────────────
+
+    async def research(
+        self,
+        query: str,
+        *,
+        depth: Literal["basic", "deep"] = "basic",
+        max_rounds: Optional[int] = None,
+        fast: bool = False,
+        scrape: bool = True,
+        query_gen: bool = True,
+        topic: Literal["general", "news", "finance"] = "general",
+        max_results: int = 5,
+        time_range: Optional[Literal["day", "week", "month", "year"]] = None,
+        wait: bool = False,
+        poll_interval: float = 5.0,
+        max_poll_interval: float = 30.0,
+        poll_timeout: float = DEEP_RESEARCH_TIMEOUT_S,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> Union[ResearchBasicResponse, ResearchDeepInitResponse, ResearchStatusResponse]:
+        body: Dict[str, Any] = {
+            "query": query,
+            "depth": depth,
+            "fast": fast,
+            "scrape": scrape,
+            "query_gen": query_gen,
+            "topic": topic,
+            "max_results": max_results,
+        }
+        if max_rounds is not None:
+            body["max_rounds"] = max_rounds
+        if time_range:
+            body["time_range"] = time_range
+
+        idem = idempotency_key
+        if depth == "deep" and idem is None:
+            idem = new_idempotency_key()
+        data = await self._post_json(
+            "/v1/research", body, idempotency_key=idem, timeout=timeout
+        )
+        if depth == "basic":
+            return ResearchBasicResponse.model_validate(data)
+        init = ResearchDeepInitResponse.model_validate(data)
+        if not wait:
+            return init
+
+        async def fetch() -> ResearchStatusResponse:
+            return await self.research_status(init.job_id)
+
+        return await poll_until_terminal_async(
+            fetch,
+            initial_interval=poll_interval,
+            max_interval=max_poll_interval,
+            poll_timeout=poll_timeout,
+        )
+
+    async def research_status(self, job_id: str) -> ResearchStatusResponse:
+        data = await self._get_json(f"/v1/research/{job_id}")
+        return ResearchStatusResponse.model_validate(data)
+
+    async def research_stream(
+        self,
+        query: str,
+        *,
+        depth: Literal["basic", "deep"] = "deep",
+        max_rounds: Optional[int] = None,
+        topic: Literal["general", "news", "finance"] = "general",
+        max_results: int = 5,
+        last_event_id: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> AsyncIterator[ResearchSseEvent]:
+        if depth == "basic":
+            async for evt in self._sse_post(
+                "/v1/research",
+                body={
+                    "query": query,
+                    "depth": "basic",
+                    "max_rounds": max_rounds or 1,
+                    "topic": topic,
+                    "max_results": max_results,
+                    "stream": True,
+                },
+                last_event_id=last_event_id,
+                timeout=timeout,
+            ):
+                yield evt
+            return
+        init = await self.research(
+            query,
+            depth="deep",
+            max_rounds=max_rounds,
+            topic=topic,
+            max_results=max_results,
+            wait=False,
+            timeout=timeout,
+        )
+        assert isinstance(init, ResearchDeepInitResponse)
+        async for evt in self._sse_get(
+            init.stream_url, last_event_id=last_event_id, timeout=timeout
+        ):
+            yield evt
+
+    # ── Internal HTTP plumbing ────────────────────────────────────────
+
+    async def _post_json(
+        self,
+        path: str,
+        body: Dict[str, Any],
+        *,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        headers = build_headers(self._api_key, idempotency_key=idempotency_key)
+        try:
+            res = await self._client.post(
+                path, json=body, headers=headers, timeout=timeout or self._timeout
+            )
+        except httpx.HTTPError as exc:
+            raise wrap_transport_error(exc) from exc
+        return decode_response(res)
+
+    async def _get_json(self, path: str, *, timeout: Optional[float] = None) -> Any:
+        headers = build_headers(self._api_key, json_body=False)
+        try:
+            res = await self._client.get(
+                path, headers=headers, timeout=timeout or self._timeout
+            )
+        except httpx.HTTPError as exc:
+            raise wrap_transport_error(exc) from exc
+        return decode_response(res)
+
+    async def _sse_post(
+        self,
+        path: str,
+        *,
+        body: Dict[str, Any],
+        last_event_id: Optional[str],
+        timeout: Optional[float],
+    ) -> AsyncIterator[ResearchSseEvent]:
+        extra: Dict[str, str] = {}
+        if last_event_id:
+            extra["last-event-id"] = last_event_id
+        headers = build_headers(self._api_key, accept="text/event-stream", extra=extra)
+        try:
+            async with self._client.stream(
+                "POST",
+                path,
+                json=body,
+                headers=headers,
+                timeout=timeout or DEEP_RESEARCH_TIMEOUT_S,
+            ) as res:
+                if not res.is_success:
+                    await res.aread()
+                    decode_response(res)
+                async for evt in iter_sse_async(res.aiter_bytes()):
+                    yield ResearchSseEvent.model_validate(evt)
+        except httpx.HTTPError as exc:
+            if isinstance(exc, BrimeError):  # pragma: no cover
+                raise
+            raise wrap_transport_error(exc) from exc
+
+    async def _sse_get(
+        self,
+        path: str,
+        *,
+        last_event_id: Optional[str],
+        timeout: Optional[float],
+    ) -> AsyncIterator[ResearchSseEvent]:
+        extra: Dict[str, str] = {}
+        if last_event_id:
+            extra["last-event-id"] = last_event_id
+        headers = build_headers(
+            self._api_key, json_body=False, accept="text/event-stream", extra=extra
+        )
+        try:
+            async with self._client.stream(
+                "GET",
+                path,
+                headers=headers,
+                timeout=timeout or DEEP_RESEARCH_TIMEOUT_S,
+            ) as res:
+                if not res.is_success:
+                    await res.aread()
+                    decode_response(res)
+                async for evt in iter_sse_async(res.aiter_bytes()):
+                    yield ResearchSseEvent.model_validate(evt)
+        except httpx.HTTPError as exc:
+            if isinstance(exc, BrimeError):  # pragma: no cover
+                raise
+            raise wrap_transport_error(exc) from exc