Metadata-Version: 2.4
Name: langchain-soul
Version: 0.1.1
Summary: The soul ecosystem for LangChain: persistent memory, identity, database schema intelligence, and SoulMate API integration.
Author-email: "Prahlad G. Menon" <menon.prahlad@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/menonpg/langchain-soul
Project-URL: Documentation, https://github.com/menonpg/langchain-soul#readme
Project-URL: Repository, https://github.com/menonpg/langchain-soul
Keywords: langchain,memory,ai,agents,llm,markdown,soul,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: soul-agent>=0.1.7
Requires-Dist: soul-schema>=0.1.0
Requires-Dist: langchain-core>=0.1.0
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"

# langchain-soul 🧠

**The soul ecosystem for LangChain.**

One package, full stack:
- **Persistent Memory** — Markdown-native, git-versionable, human-readable
- **Hybrid Retrieval** — RAG + RLM via [soul-agent](https://github.com/menonpg/soul.py)
- **Database Intelligence** — Auto-generated semantic layers via [soul-schema](https://github.com/menonpg/soul-schema)
- **Managed Cloud Option** — [SoulMate](https://menonpg.github.io/soulmate) handles memory infrastructure for you

## Choose Your Setup

| Setup | Best For | Storage |
|-------|----------|---------|
| **Local** (default) | Development, git-tracked projects | `SOUL.md` + `MEMORY.md` files |
| **SoulMate** (managed) | Production, teams, zero-infra | Cloud API (we handle it) |

Both use the same soul-agent RAG+RLM under the hood.

## Install

```bash
pip install langchain-soul
```

This automatically installs:
- `soul-agent` — Hybrid RAG+RLM memory
- `soul-schema` — Database semantic layer generator

## Quick Start

### Basic Memory

```python
from langchain_soul import SoulMemory
from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI

# Create markdown-based memory with full RAG+RLM
memory = SoulMemory()

# Use it with your chain
chain = ConversationChain(llm=ChatOpenAI(), memory=memory)
response = chain.predict(input="Hello!")
```

Your conversations are stored in `MEMORY.md` — human-readable, git-versionable, no database required.

### With RunnableWithMessageHistory

```python
from langchain_soul import SoulChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory

chain_with_history = RunnableWithMessageHistory(
    chain,
    lambda session_id: SoulChatMessageHistory(
        memory_path=f"memory/{session_id}.md"
    ),
)
```

### Semantic Search

```python
# Search past conversations
results = memory.recall("What did we discuss about databases?")
for result in results:
    print(f"[{result['score']:.2f}] {result['content']}")
```

### Database Schema Intelligence

Give your agents understanding of database structure:

```python
from langchain_soul import SchemaMemory

# Connect to any SQLAlchemy-compatible database
schema = SchemaMemory("postgresql://user:pass@host/db")

# Auto-generate semantic descriptions using LLM
schema.generate()

# Get context for natural language queries
context = schema.context_for("Show me revenue by region")
```

### SoulMate: Managed Memory (Recommended for Production)

Don't want to manage files? **SoulMate** is the managed version — same RAG+RLM, zero infrastructure:

```python
from langchain_soul import SoulMateMemory
from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI

# Connect to SoulMate cloud
memory = SoulMateMemory(api_key="your-key")
chain = ConversationChain(llm=ChatOpenAI(), memory=memory)

# Same interface, managed infrastructure
response = chain.predict(input="Hello!")
```

### Factory Function

```python
from langchain_soul import create_memory

# Local file-based (default)
memory = create_memory()

# SoulMate managed
memory = create_memory("soulmate", api_key="...")
```

## Architecture

```
┌──────────────────────────────────────────────────────────┐
│                     langchain-soul                        │
│                                                          │
│   ┌─────────────┐     ┌───────────────┐                 │
│   │ SoulMemory  │     │SoulMateMemory │                 │
│   │  (local)    │     │  (managed)    │                 │
│   └──────┬──────┘     └───────┬───────┘                 │
│          │                    │                          │
│          ▼                    ▼                          │
│   ┌─────────────────────────────────────────────────┐   │
│   │              soul-agent (RAG + RLM)             │   │
│   └─────────────────────────────────────────────────┘   │
│                                                          │
│   ┌──────────────────┐    ┌─────────────────────────┐   │
│   │   soul-schema    │    │    SoulMate API         │   │
│   │ (db intelligence)│    │  (managed memory)       │   │
│   └──────────────────┘    └─────────────────────────┘   │
└──────────────────────────────────────────────────────────┘
```

## Part of the Soul Ecosystem

- [soul-agent](https://github.com/menonpg/soul.py) — Core RAG + RLM library
- [soul-schema](https://github.com/menonpg/soul-schema) — Database semantic layer generator
- [crewai-soul](https://github.com/menonpg/crewai-soul) — CrewAI integration
- **langchain-soul** — LangChain integration (this package)
- [llamaindex-soul](https://github.com/menonpg/llamaindex-soul) — LlamaIndex integration
- [SoulMate](https://menonpg.github.io/soulmate) — Managed cloud service

## License

MIT
