Metadata-Version: 2.4
Name: langchain-onebrain
Version: 0.1.0
Summary: LangChain integration for OneBrain — persistent AI memory layer
Project-URL: Homepage, https://onebrain.rocks
Project-URL: Repository, https://github.com/azappnew/langchain-onebrain
Project-URL: Documentation, https://onebrain.rocks/docs/integrations/langchain
Project-URL: Issues, https://github.com/azappnew/langchain-onebrain/issues
Project-URL: Changelog, https://github.com/azappnew/langchain-onebrain/blob/main/CHANGELOG.md
Author-email: AZapp One <dev@onebrain.rocks>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,chat-history,langchain,llm,memory,onebrain,retriever
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: langchain-core<1,>=0.3
Requires-Dist: onebrain-sdk<2,>=1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# langchain-onebrain

[![PyPI version](https://img.shields.io/pypi/v/langchain-onebrain.svg)](https://pypi.org/project/langchain-onebrain/)
[![Python 3.9+](https://img.shields.io/pypi/pyversions/langchain-onebrain.svg)](https://pypi.org/project/langchain-onebrain/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

LangChain integration for [OneBrain](https://onebrain.rocks) — a persistent AI memory layer for humans and agents. This package provides chat message history, a retriever, and agent tools that connect LangChain to OneBrain via the official Python SDK.

**Architecture**: This package wraps `onebrain-sdk` (not raw HTTP). If OneBrain's API changes, only the SDK needs updating — this package stays stable.

---

## Installation

```bash
pip install langchain-onebrain
```

Requires Python 3.9+.

**Dependencies:**
- `langchain-core>=0.3,<1`
- `onebrain-sdk>=1.0,<2`

---

## Configuration

Set your OneBrain API key as an environment variable or pass it directly:

```bash
export ONEBRAIN_API_KEY="ob_your_prefix:your_secret_here"
```

All components accept `api_key` and `base_url` parameters to override the defaults.

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `ONEBRAIN_API_KEY` | Your OneBrain API key | — (required) |
| `ONEBRAIN_BASE_URL` | Base URL for self-hosted instances | `https://onebrain.rocks/api/eu` |

### Getting an API Key

1. Sign in at [onebrain.rocks/dashboard](https://onebrain.rocks/dashboard).
2. Navigate to **Settings > API Keys**.
3. Click **Create API Key** and copy the full key (`ob_prefix:secret`).

---

## Quick Start

### Chat Message History

Store and retrieve conversation messages as OneBrain memories:

```python
from langchain_onebrain import OneBrainChatMessageHistory
from langchain_core.messages import HumanMessage, AIMessage

# Create a history backed by OneBrain
history = OneBrainChatMessageHistory(
    api_key="ob_xxx:secret",
    session_id="session-abc-123",
)

# Add messages
history.add_user_message("What is the weather like?")
history.add_ai_message("I don't have real-time weather data.")

# Retrieve all messages
for msg in history.messages:
    print(f"{msg.type}: {msg.content}")

# Clear (archives messages, does not delete)
history.clear()
```

#### With ConversationChain

```python
from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI
from langchain_onebrain import OneBrainChatMessageHistory

llm = ChatOpenAI(model="gpt-4")
memory_history = OneBrainChatMessageHistory(session_id="user-42")

chain = ConversationChain(
    llm=llm,
    memory=ConversationBufferMemory(
        chat_memory=memory_history,
        return_messages=True,
    ),
)

response = chain.predict(input="Tell me about quantum computing.")
```

---

### Retriever

Search OneBrain memories and return them as LangChain documents:

```python
from langchain_onebrain import OneBrainRetriever

retriever = OneBrainRetriever(
    api_key="ob_xxx:secret",
    top_k=5,
    search_mode="hybrid",  # "keyword", "vector", or "hybrid"
)

# Use directly
docs = retriever.invoke("user preferences for dark mode")
for doc in docs:
    print(doc.page_content)
    print(doc.metadata)  # id, type, confidence, score, source_type, created_at
```

#### With RetrievalQA

```python
from langchain.chains import RetrievalQA
from langchain_openai import ChatOpenAI
from langchain_onebrain import OneBrainRetriever

llm = ChatOpenAI(model="gpt-4")
retriever = OneBrainRetriever(top_k=10, search_mode="hybrid")

qa = RetrievalQA.from_chain_type(
    llm=llm,
    retriever=retriever,
    chain_type="stuff",
)

answer = qa.invoke("What are the user's coding preferences?")
print(answer["result"])
```

---

### Agent Tools

Four tools for use with LangChain agents:

```python
from langchain_onebrain import (
    OneBrainSearchTool,
    OneBrainWriteTool,
    OneBrainContextTool,
    OneBrainEntityTool,
)

# Create tools
search = OneBrainSearchTool(api_key="ob_xxx:secret")
write = OneBrainWriteTool(api_key="ob_xxx:secret")
context = OneBrainContextTool(api_key="ob_xxx:secret")
entity = OneBrainEntityTool(api_key="ob_xxx:secret")

# Use with an agent
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

llm = ChatOpenAI(model="gpt-4")
tools = [search, write, context, entity]

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant with access to the user's memory."),
    MessagesPlaceholder("chat_history", optional=True),
    ("human", "{input}"),
    MessagesPlaceholder("agent_scratchpad"),
])

agent = create_openai_tools_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)

result = executor.invoke({"input": "What do you know about my work projects?"})
print(result["output"])
```

#### Tool Reference

| Tool | Name | Description |
|------|------|-------------|
| `OneBrainSearchTool` | `onebrain_search` | Search memories with keyword/vector/hybrid modes |
| `OneBrainWriteTool` | `onebrain_write` | Store new memories (facts, preferences, goals, etc.) |
| `OneBrainContextTool` | `onebrain_context` | Get optimized user context (brief/assistant/project/deep) |
| `OneBrainEntityTool` | `onebrain_entity` | List entities (people, organizations, tools) |

---

## Self-Hosted Setup

OneBrain supports self-hosted deployments. Point the SDK to your instance:

```python
from langchain_onebrain import OneBrainRetriever

retriever = OneBrainRetriever(
    api_key="ob_xxx:secret",
    base_url="https://brain.your-company.com/api/v1",
)
```

Or set the environment variable:

```bash
export ONEBRAIN_BASE_URL="https://brain.your-company.com/api/v1"
```

---

## API Reference

### `OneBrainChatMessageHistory`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str \| None` | `None` | OneBrain API key (or `ONEBRAIN_API_KEY` env var) |
| `session_id` | `str` | `"default"` | Unique session identifier |
| `base_url` | `str \| None` | `None` | API base URL override |

**Methods:**
- `messages` — Property returning `List[BaseMessage]`
- `add_message(message)` — Store a single message
- `add_messages(messages)` — Store multiple messages
- `clear()` — Archive all session messages

### `OneBrainRetriever`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str \| None` | `None` | OneBrain API key |
| `top_k` | `int` | `10` | Maximum results |
| `search_mode` | `str` | `"hybrid"` | Search mode: keyword/vector/hybrid |
| `base_url` | `str \| None` | `None` | API base URL override |
| `alpha` | `float \| None` | `None` | Keyword/vector balance (0.0-1.0) |

**Methods:**
- `invoke(query)` / `_get_relevant_documents(query)` — Returns `List[Document]`

### `OneBrainSearchTool`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `str` | — | Search query (required) |
| `top_k` | `int` | `10` | Maximum results |
| `mode` | `str` | `"hybrid"` | Search mode |

### `OneBrainWriteTool`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `title` | `str` | — | Memory title (required) |
| `body` | `str` | — | Memory content (required) |
| `memory_type` | `str` | `"fact"` | Type: fact/preference/decision/goal/experience/skill |

### `OneBrainContextTool`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `scope` | `str` | `"deep"` | Scope: brief/assistant/project/deep |

### `OneBrainEntityTool`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `entity_type` | `str \| None` | `None` | Filter by entity type |
| `limit` | `int` | `20` | Maximum results |

---

## Development

```bash
git clone https://github.com/azappnew/langchain-onebrain.git
cd langchain-onebrain
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# With coverage
pytest tests/ -v --cov=langchain_onebrain --cov-report=term-missing

# Lint
ruff check src/ tests/

# Type check
mypy src/
```

---

## License

MIT License. See [LICENSE](LICENSE) for details.

Copyright (c) 2026 AZapp One.
