Metadata-Version: 2.4
Name: langchain-thrindex
Version: 0.1.0
Summary: Official LangChain / LangGraph integration for Thrindex — persistent semantic memory for AI agents.
Author-email: Thrindex <hello@thrindex.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://thrindex.com
Project-URL: Documentation, https://docs.thrindex.com
Project-URL: Repository, https://github.com/thrindex/thrindex.git
Project-URL: Bug Tracker, https://github.com/thrindex/thrindex/issues
Keywords: langchain,langgraph,ai,agents,memory,llm,semantic-search,rag,thrindex
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: thrindex>=0.2.1
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langgraph>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: anyio[trio]>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.9.0; extra == "dev"
Requires-Dist: mypy>=1.13.0; extra == "dev"

# langchain-thrindex

Official [LangChain](https://python.langchain.com) / [LangGraph](https://langchain-ai.github.io/langgraph/) integration for [Thrindex](https://thrindex.com) — persistent, semantically-searchable long-term memory for AI agents.

## Installation

```bash
pip install langchain-thrindex
```

## Components

| Class | Interface | Use case |
|---|---|---|
| `ThrindexStore` | `langgraph.store.base.BaseStore` | LangGraph agents — long-term memory across threads |
| `ThrindexRetriever` | `langchain_core.retrievers.BaseRetriever` | LCEL chains, RAG pipelines |

---

## ThrindexStore — LangGraph agents

The primary integration. Pass `ThrindexStore` to `graph.compile(store=store)` and your LangGraph agent gets persistent memory that survives restarts and scales across deployments.

```python
from langchain_thrindex import ThrindexStore
from langgraph.prebuilt import create_react_agent

store = ThrindexStore(
    api_key="th_live_...",
    agent_id="customer-support-bot",  # stable identifier for your agent
)

# Compile the agent with persistent memory
agent = create_react_agent(
    model="openai:gpt-4o",
    tools=[...],
    store=store,
)

# The agent now reads and writes long-term memories automatically
result = agent.invoke(
    {"messages": [{"role": "user", "content": "My name is Alice and I prefer dark mode."}]},
    config={"configurable": {"thread_id": "thread-1"}},
)
```

### Manual store operations

```python
# Store a fact
store.put(
    ("memories", "user-42"),  # namespace: (category, user_id)
    "preference-display",     # unique key within the namespace
    {"content": "User prefers dark mode and compact layout"},
)

# Semantic search
results = store.search(
    ("memories", "user-42"),
    query="display preferences",
    limit=5,
)
for item in results:
    print(item.value["content"], item.score)

# Get by key
item = store.get(("memories", "user-42"), "preference-display")

# Delete
store.delete(("memories", "user-42"), "preference-display")
```

### Async

All operations have async counterparts:

```python
await store.aput(namespace, key, value)
item = await store.aget(namespace, key)
results = await store.asearch(namespace, query="...")
await store.adelete(namespace, key)
```

### Namespace → Thrindex mapping

| LangGraph | Thrindex |
|---|---|
| `agent_id` constructor arg | `agent_id` in every API call |
| `"/".join(namespace)` | `user_id` in every API call |

---

## ThrindexRetriever — LCEL chains

```python
from langchain_thrindex import ThrindexRetriever
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

retriever = ThrindexRetriever(
    api_key="th_live_...",
    agent_id="my-agent",
    user_id="user-42",
    k=5,
    task_context="answering user questions about product settings",
)

prompt = ChatPromptTemplate.from_template(
    "Use the following memories to answer the question.\n\n"
    "Memories:\n{context}\n\n"
    "Question: {question}"
)

chain = (
    {"context": retriever, "question": lambda x: x}
    | prompt
    | ChatOpenAI(model="gpt-4o")
    | StrOutputParser()
)

answer = chain.invoke("What display settings does the user prefer?")
```

---

## Configuration reference

### ThrindexStore

| Parameter | Type | Default | Description |
|---|---|---|---|
| `api_key` | `str` | required | Thrindex API key |
| `agent_id` | `str` | `"default"` | Stable agent identifier |
| `base_url` | `str` | `"https://api.thrindex.com"` | API base URL (override for self-hosted) |
| `timeout` | `float` | `30.0` | Request timeout in seconds |
| `max_retries` | `int` | `3` | Retries on transient failures |
| `extract` | `bool` | `True` | Run LLM fact extraction on stored memories |

### ThrindexRetriever

Accepts `api_key`, `agent_id`, `user_id`, `k`, `task_context`, `base_url`, `timeout`, `max_retries`. See class docstring for full details.

---

## Links

- [Thrindex docs](https://docs.thrindex.com)
- [LangGraph store guide](https://langchain-ai.github.io/langgraph/how-tos/memory/manage-conversation-history/)
- [GitHub](https://github.com/thrindex/thrindex)
