brime 0.1.0__tar.gz

brime-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.egg

brime-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 — 2026-05-06
+
+Initial release. Beta.
+
+### Added
+- `Brime` synchronous client and `AsyncBrime` asynchronous client
+- `search`, `extract`, `research`, `research_status`, `research_stream` methods
+- Native `/v1/*` endpoint coverage (Brime-native surface — Tavily/Exa/Parallel users should use those vendors' official SDKs against the matching `/tavily/*`, `/exa/*`, `/parallel/*` paths)
+- `research(depth="deep", wait=True)` blocking polling helper with exponential backoff
+- Pydantic v2 response models with full type hints (`py.typed`)
+- Error hierarchy: `BrimeError` → `AuthenticationError`, `RateLimitError`, `InsufficientCreditsError`, `InvalidRequestError`, `NotFoundError`, `UpstreamError`, `InternalError`
+- Auto-generated `Idempotency-Key` for `extract` and deep `research` calls
+- SSE parser with fragmented-chunk and `[DONE]` terminator handling
+- `BRIME_API_KEY` and `BRIME_BASE_URL` env-var fallbacks

brime-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brime
+
+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.

brime-0.1.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: brime
+Version: 0.1.0
+Summary: Official Python SDK for the Brime API (search · extract · research)
+Project-URL: Homepage, https://brime.dev
+Project-URL: Documentation, https://docs.brime.dev
+Project-URL: Repository, https://github.com/brime-dev/brime-python
+Project-URL: Issues, https://github.com/brime-dev/brime-python/issues
+Author-email: Brime <support@brime.dev>
+License: MIT License
+        
+        Copyright (c) 2026 Brime
+        
+        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.
+License-File: LICENSE
+Keywords: agents,brime,extract,llm,rag,research,search
+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.9
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# brime
+
+**The live-web toolkit for AI apps.** One API key. One SDK. Search, scrape, and research the open web — clean output, sane defaults, no plumbing.
+
+```bash
+pip install brime
+```
+
+Python 3.9+. Sync and async clients. Fully typed (`py.typed`). Single dependency tree: `httpx` + `pydantic`.
+
+## Why brime?
+
+- **One key, three primitives.** `search`, `extract`, `research` — the shape every AI app needs from the web.
+- **Tuned defaults.** No depth selectors, no round counters, no knobs to babysit. The gateway is tuned for you; you pass a query, you get a clean answer.
+- **Drop-in compatible.** Already on Tavily, Exa, or Parallel? Point their SDK at our adapter URL and your code keeps working. Migrate when you're ready.
+- **Honest pricing.** Flat per-call credits. 0.5 for search, 1 per URL for extract, 5 for research. No surprises.
+
+## 30 seconds
+
+```python
+from brime import Brime
+
+brime = Brime()  # reads BRIME_API_KEY
+
+# Live answer + ranked sources, sub-second.
+result = brime.search(query="what changed in the latest TypeScript release")
+print(result.answer)
+```
+
+That's the whole shape. Same pattern for `extract` and `research`.
+
+## What you can build
+
+### Search the open web
+
+```python
+result = brime.search(
+    query="tesla earnings",
+    topic="finance",       # optional: news / general / finance recency hint
+    time_range="week",     # optional: day / week / month / year
+    domains=["sec.gov"],   # optional allow-list
+)
+```
+
+### Turn any URL into clean markdown
+
+```python
+result = brime.extract(urls=[
+    "https://example.com",
+    "https://en.wikipedia.org/wiki/BM25",
+])
+
+for r in result.results:
+    print(r.url, len(r.markdown))
+for f in result.failed:
+    print("skipped", f.url, f.error.message)
+```
+
+Handles HTML, PDF, DOCX, and JavaScript-heavy SPAs. The smart-clean pipeline strips chrome, nav, cookie banners, and template noise — what's left is the article.
+
+### Multi-step research with citations
+
+```python
+result = brime.research(
+    query="compare frontier coding models with concrete benchmark numbers",
+)
+
+print(result.answer)
+print(f"{len(result.sources)} sources cited")
+```
+
+One call, ~30–90 seconds, real synthesis from real sources.
+
+Live progress? Stream it:
+
+```python
+for evt in brime.research_stream(query="..."):
+    print(evt.event, evt.data)
+    if evt.event in ("complete", "error", "timeout"):
+        break
+```
+
+## Authentication
+
+```bash
+export BRIME_API_KEY="sk-brime-..."
+```
+
+```python
+Brime()                        # uses BRIME_API_KEY
+Brime(api_key="sk-brime-...")  # explicit
+Brime(base_url="https://...")  # staging override (or BRIME_BASE_URL env)
+```
+
+Get a key at [brime.dev](https://brime.dev) — the free tier comes with 1,000 credits/month and no card.
+
+## Async
+
+Every method is mirrored on `AsyncBrime`:
+
+```python
+import asyncio
+from brime import AsyncBrime
+
+async def main():
+    async with AsyncBrime() as brime:
+        result = await brime.search(query="python async io")
+        print(result.answer)
+
+asyncio.run(main())
+```
+
+Async streaming works the same way:
+
+```python
+async with AsyncBrime() as brime:
+    async for evt in brime.research_stream(query="..."):
+        if evt.event == "complete":
+            print(evt.data)
+            break
+```
+
+## Error handling
+
+Typed exceptions, predictable surface area:
+
+```python
+from brime import (
+    BrimeError,
+    AuthenticationError,
+    RateLimitError,
+    InsufficientCreditsError,
+)
+
+try:
+    brime.search(query="...")
+except AuthenticationError:
+    ...  # bad key
+except RateLimitError:
+    ...  # back off
+except InsufficientCreditsError:
+    ...  # top up
+except BrimeError as e:
+    print(e.code, e.message)
+```
+
+## Idempotency, baked in
+
+`extract` calls require an `Idempotency-Key` — the SDK auto-generates one per call so accidental retries never double-charge. Pin it yourself for cross-process dedup:
+
+```python
+brime.extract(
+    urls=["https://x"],
+    idempotency_key="user-42-prefetch-2026-05",
+)
+```
+
+## Configuration
+
+| Constructor arg | Env var          | Default                  |
+|-----------------|------------------|--------------------------|
+| `api_key`       | `BRIME_API_KEY`  | — (required)             |
+| `base_url`      | `BRIME_BASE_URL` | `https://api.brime.dev`  |
+| `timeout`       | —                | `30.0` seconds           |
+
+Per-call override: `brime.search(query="...", timeout=60)`.
+
+## Already using Tavily, Exa, or Parallel?
+
+You don't have to rip them out. Brime exposes wire-compatible adapters:
+
+```python
+TavilyClient(api_key, api_base_url="https://api.brime.dev/tavily")
+Exa(api_key=..., base_url="https://api.brime.dev/exa")
+Parallel(api_key, base_url="https://api.brime.dev/parallel")
+```
+
+Same response shapes, same code. Switch to the native `brime` SDK when you want the extras (research synthesis, SSE streaming, smart-clean extract).
+
+## Links
+
+- Docs — [docs.brime.dev](https://docs.brime.dev)
+- API reference — [docs.brime.dev/api-reference](https://docs.brime.dev/api-reference)
+- Status — [brime.dev](https://brime.dev)
+- Issues — [github.com/brime-dev/brime-python/issues](https://github.com/brime-dev/brime-python/issues)
+
+## License
+
+MIT © Brime

brime-0.1.0/README.md

@@ -0,0 +1,189 @@
+# brime
+
+**The live-web toolkit for AI apps.** One API key. One SDK. Search, scrape, and research the open web — clean output, sane defaults, no plumbing.
+
+```bash
+pip install brime
+```
+
+Python 3.9+. Sync and async clients. Fully typed (`py.typed`). Single dependency tree: `httpx` + `pydantic`.
+
+## Why brime?
+
+- **One key, three primitives.** `search`, `extract`, `research` — the shape every AI app needs from the web.
+- **Tuned defaults.** No depth selectors, no round counters, no knobs to babysit. The gateway is tuned for you; you pass a query, you get a clean answer.
+- **Drop-in compatible.** Already on Tavily, Exa, or Parallel? Point their SDK at our adapter URL and your code keeps working. Migrate when you're ready.
+- **Honest pricing.** Flat per-call credits. 0.5 for search, 1 per URL for extract, 5 for research. No surprises.
+
+## 30 seconds
+
+```python
+from brime import Brime
+
+brime = Brime()  # reads BRIME_API_KEY
+
+# Live answer + ranked sources, sub-second.
+result = brime.search(query="what changed in the latest TypeScript release")
+print(result.answer)
+```
+
+That's the whole shape. Same pattern for `extract` and `research`.
+
+## What you can build
+
+### Search the open web
+
+```python
+result = brime.search(
+    query="tesla earnings",
+    topic="finance",       # optional: news / general / finance recency hint
+    time_range="week",     # optional: day / week / month / year
+    domains=["sec.gov"],   # optional allow-list
+)
+```
+
+### Turn any URL into clean markdown
+
+```python
+result = brime.extract(urls=[
+    "https://example.com",
+    "https://en.wikipedia.org/wiki/BM25",
+])
+
+for r in result.results:
+    print(r.url, len(r.markdown))
+for f in result.failed:
+    print("skipped", f.url, f.error.message)
+```
+
+Handles HTML, PDF, DOCX, and JavaScript-heavy SPAs. The smart-clean pipeline strips chrome, nav, cookie banners, and template noise — what's left is the article.
+
+### Multi-step research with citations
+
+```python
+result = brime.research(
+    query="compare frontier coding models with concrete benchmark numbers",
+)
+
+print(result.answer)
+print(f"{len(result.sources)} sources cited")
+```
+
+One call, ~30–90 seconds, real synthesis from real sources.
+
+Live progress? Stream it:
+
+```python
+for evt in brime.research_stream(query="..."):
+    print(evt.event, evt.data)
+    if evt.event in ("complete", "error", "timeout"):
+        break
+```
+
+## Authentication
+
+```bash
+export BRIME_API_KEY="sk-brime-..."
+```
+
+```python
+Brime()                        # uses BRIME_API_KEY
+Brime(api_key="sk-brime-...")  # explicit
+Brime(base_url="https://...")  # staging override (or BRIME_BASE_URL env)
+```
+
+Get a key at [brime.dev](https://brime.dev) — the free tier comes with 1,000 credits/month and no card.
+
+## Async
+
+Every method is mirrored on `AsyncBrime`:
+
+```python
+import asyncio
+from brime import AsyncBrime
+
+async def main():
+    async with AsyncBrime() as brime:
+        result = await brime.search(query="python async io")
+        print(result.answer)
+
+asyncio.run(main())
+```
+
+Async streaming works the same way:
+
+```python
+async with AsyncBrime() as brime:
+    async for evt in brime.research_stream(query="..."):
+        if evt.event == "complete":
+            print(evt.data)
+            break
+```
+
+## Error handling
+
+Typed exceptions, predictable surface area:
+
+```python
+from brime import (
+    BrimeError,
+    AuthenticationError,
+    RateLimitError,
+    InsufficientCreditsError,
+)
+
+try:
+    brime.search(query="...")
+except AuthenticationError:
+    ...  # bad key
+except RateLimitError:
+    ...  # back off
+except InsufficientCreditsError:
+    ...  # top up
+except BrimeError as e:
+    print(e.code, e.message)
+```
+
+## Idempotency, baked in
+
+`extract` calls require an `Idempotency-Key` — the SDK auto-generates one per call so accidental retries never double-charge. Pin it yourself for cross-process dedup:
+
+```python
+brime.extract(
+    urls=["https://x"],
+    idempotency_key="user-42-prefetch-2026-05",
+)
+```
+
+## Configuration
+
+| Constructor arg | Env var          | Default                  |
+|-----------------|------------------|--------------------------|
+| `api_key`       | `BRIME_API_KEY`  | — (required)             |
+| `base_url`      | `BRIME_BASE_URL` | `https://api.brime.dev`  |
+| `timeout`       | —                | `30.0` seconds           |
+
+Per-call override: `brime.search(query="...", timeout=60)`.
+
+## Already using Tavily, Exa, or Parallel?
+
+You don't have to rip them out. Brime exposes wire-compatible adapters:
+
+```python
+TavilyClient(api_key, api_base_url="https://api.brime.dev/tavily")
+Exa(api_key=..., base_url="https://api.brime.dev/exa")
+Parallel(api_key, base_url="https://api.brime.dev/parallel")
+```
+
+Same response shapes, same code. Switch to the native `brime` SDK when you want the extras (research synthesis, SSE streaming, smart-clean extract).
+
+## Links
+
+- Docs — [docs.brime.dev](https://docs.brime.dev)
+- API reference — [docs.brime.dev/api-reference](https://docs.brime.dev/api-reference)
+- Status — [brime.dev](https://brime.dev)
+- Issues — [github.com/brime-dev/brime-python/issues](https://github.com/brime-dev/brime-python/issues)
+
+## License
+
+MIT © Brime

brime-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "brime"
+version = "0.1.0"
+description = "Official Python SDK for the Brime API (search · extract · research)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Brime", email = "support@brime.dev" }]
+keywords = ["brime", "search", "extract", "research", "rag", "llm", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27,<1.0",
+    "pydantic>=2.6,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "mypy>=1.10",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://brime.dev"
+Documentation = "https://docs.brime.dev"
+Repository = "https://github.com/brime-dev/brime-python"
+Issues = "https://github.com/brime-dev/brime-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/brime"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/brime", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "live: marks tests requiring BRIME_API_KEY env var (deselect with -m 'not live')",
+]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+python_version = "3.9"
+files = ["src/brime"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "RUF"]
+ignore = ["E501"]

brime-0.1.0/src/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)