Metadata-Version: 2.4
Name: langchain-brime
Version: 0.1.0
Summary: LangChain integration for the Brime API (search · extract · research) — tools and retriever
Project-URL: Homepage, https://brime.dev
Project-URL: Documentation, https://docs.brime.dev/integrations/langchain
Project-URL: Repository, https://github.com/brime-dev/brime-langchain
Project-URL: Issues, https://github.com/brime-dev/brime-langchain/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,langchain,rag,research,retriever,search,tools
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: brime>=0.1.0
Requires-Dist: langchain-core<2.0,>=0.3
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: ruff>=0.6; extra == 'dev'
Provides-Extra: test-integration
Requires-Dist: langchain-tests>=0.3; extra == 'test-integration'
Description-Content-Type: text/markdown

# langchain-brime

**LangChain meets the live web.** Drop the [Brime API](https://brime.dev) into any LangChain agent, chain, or RAG pipeline — as four typed tools and a retriever you can plug in unchanged.

```bash
pip install langchain-brime
```

Python 3.9+. Sync and async. Fully typed (`py.typed`). Passes the official LangChain `ToolsUnitTests` compliance suite.

## What you get

| Class            | Type            | What it does                                                |
|------------------|-----------------|-------------------------------------------------------------|
| `BrimeSearch`    | `BaseTool`      | Fast SERP search with snippets + synthesised answer.        |
| `BrimeExtract`   | `BaseTool`      | Any URL → clean markdown (HTML / PDF / DOCX / SPA).         |
| `BrimeResearch`  | `BaseTool`      | Multi-round agent research with citations.                  |
| `BrimeRetriever` | `BaseRetriever` | Live-web retriever for RAG — returns LangChain `Document`s. |

One API key powers all four. One set of tuned defaults. No knobs to babysit.

## 30 seconds

```python
from langchain.agents import create_agent
from langchain_brime import BrimeSearch, BrimeExtract

agent = create_agent(
    model="anthropic:claude-3-5-haiku-latest",
    tools=[BrimeSearch(), BrimeExtract()],
    system_prompt="You are a research assistant.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "What is BM25 ranking? Cite sources."}],
})
print(result["messages"][-1].content)
```

## RAG without the RAG plumbing

`BrimeRetriever` returns standard LangChain `Document`s — drop it into any retrieval chain and you're querying the live web with BM25-ranked chunks:

```python
from langchain_brime import BrimeRetriever
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain.chat_models import init_chat_model

retriever = BrimeRetriever(k=5)
llm = init_chat_model("anthropic:claude-3-5-haiku-latest")

prompt = ChatPromptTemplate.from_template(
    "Context:\n{context}\n\nQuestion: {question}\n\nAnswer with citations."
)
chain = ({"context": retriever, "question": RunnablePassthrough()} | prompt | llm)

print(chain.invoke("How does BM25 weight term frequency?").content)
```

Each `Document` carries `page_content` (ranked chunk) and rich metadata: `url`, `title`, `score`, `published_date`, `source="brime"`.

## Async, end-to-end

```python
import asyncio
from langchain_brime import BrimeSearch

async def main():
    result = await BrimeSearch().ainvoke({"query": "python async io patterns"})
    print(result)

asyncio.run(main())
```

Every tool has `_arun`. The retriever has `_aget_relevant_documents`. No surprises.

## Authentication

```bash
export BRIME_API_KEY="sk-brime-..."
```

```python
BrimeSearch()                        # uses BRIME_API_KEY
BrimeSearch(api_key="sk-brime-...")  # explicit
BrimeSearch(base_url="https://...")  # staging override (or BRIME_BASE_URL)
```

Get a key at [brime.dev](https://brime.dev) — free tier: 1,000 credits/month, no card.

## Tool reference

### `BrimeSearch`

| Field         | Default     | Notes                                              |
|---------------|-------------|----------------------------------------------------|
| `query`       | (required)  | Natural-language query                             |
| `topic`       | `"general"` | `general` · `news` · `finance` (recency hint)      |
| `max_results` | 5           | 1–20                                               |
| `time_range`  | None        | `day` · `week` · `month` · `year`                  |

Returns a markdown string with a synthesised answer plus a `Sources:` list.

### `BrimeExtract`

| Field              | Default | Notes                                    |
|--------------------|---------|------------------------------------------|
| `urls`             | (req.)  | List of URLs (1–10)                      |
| `include_metadata` | False   | Add extra metadata fields per result     |

Returns markdown with a `## <url>` heading per page, plus a `## Failed URLs` block if any failed.

### `BrimeResearch`

| Field         | Default     | Notes                                       |
|---------------|-------------|---------------------------------------------|
| `query`       | (required)  | Research question                           |
| `topic`       | `"general"` | Recency hint                                |
| `max_results` | 5           | Sources per round, 1–20                     |

Single tuned multi-round flow (~30–90 s) with cited synthesis.

### `BrimeRetriever`

| Field             | Default     | Notes                                                |
|-------------------|-------------|------------------------------------------------------|
| `k`               | 5           | Max documents (1–20)                                 |
| `topic`           | `"general"` | Recency hint                                         |
| `time_range`      | None        | Recency window                                       |
| `domains`         | None        | Domain allowlist                                     |
| `exclude_domains` | None        | Domain denylist                                      |
| `include_answer`  | False       | Skip the LLM answer when used purely for retrieval   |

## Why this instead of writing your own wrapper?

- **One package, four classes.** Search, extract, research, and retriever — all sharing one HTTP client (`brime` SDK).
- **Idempotency, handled.** Auto `Idempotency-Key` for `extract` (Brime API requirement, easy to miss).
- **Async parity throughout.** No partially-async surface area.
- **LangChain-tested.** Passes the official `ToolsUnitTests` compliance suite (args schema serialisable, async parity, no override violations).

## Compatibility

- Python 3.9+
- `langchain-core` 0.3 – 1.x
- Backed by [`brime`](https://pypi.org/project/brime/) Python SDK ≥ 0.1.0

## Links

- Docs — [docs.brime.dev](https://docs.brime.dev)
- LangChain integration guide — [docs.brime.dev/sdks/langchain](https://docs.brime.dev/sdks/langchain)
- Status — [brime.dev](https://brime.dev)
- Issues — [github.com/brime-dev/brime-langchain/issues](https://github.com/brime-dev/brime-langchain/issues)

## License

MIT © Brime
