Metadata-Version: 2.4
Name: crewai-soul
Version: 0.3.1
Summary: The soul ecosystem for CrewAI: persistent memory, identity, database schema intelligence, and enterprise API integration.
Author-email: "Prahlad G. Menon" <menon.prahlad@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/menonpg/crewai-soul
Project-URL: Documentation, https://github.com/menonpg/crewai-soul#readme
Project-URL: Repository, https://github.com/menonpg/crewai-soul
Keywords: crewai,memory,ai,agents,llm,markdown,soul,rag,semantic-layer,soulmate
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: httpx>=0.25.0
Provides-Extra: crewai
Requires-Dist: crewai>=0.100.0; extra == "crewai"

# crewai-soul 🧠

**The soul ecosystem for CrewAI agents.**

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 crewai-soul
```

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

## Quick Start

### Basic Memory

```python
from crewai import Crew, Agent, Task
from crewai_soul import SoulMemory

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

# Use it with your crew
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    memory=memory,
)

result = crew.kickoff()
```

Your crew's memories are stored in `MEMORY.md` — human-readable, git-versionable, no database required.

### Database Schema Intelligence

Give your agents understanding of database structure:

```python
from crewai_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")
# Returns formatted markdown with relevant tables/columns

# Use in agent prompts
agent = Agent(
    role="Data Analyst",
    goal="Answer business questions with SQL",
    backstory=f"You have access to this schema:\n{schema.to_markdown()}"
)
```

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

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

```python
from crewai_soul import SoulMateClient

client = SoulMateClient(
    api_key="your-key",
    tenant_id="your-org"
)

# Store memories in the cloud
client.remember("Critical decision: We're going with PostgreSQL", scope="/project/alpha")

# Semantic search across all memories
results = client.recall("database decisions")

# Full RAG+RLM question answering
answer = client.ask("What database did we choose for Project Alpha?")
```

## Why crewai-soul?

| Feature | CrewAI Built-in | crewai-soul |
|---------|-----------------|-------------|
| Storage | Vector database | Markdown files + optional vectors |
| Human-readable | ❌ | ✅ |
| Git-versionable | ❌ | ✅ |
| Database schema context | ❌ | ✅ (soul-schema) |
| Enterprise multi-tenant | ❌ | ✅ (SoulMate API) |
| RAG + RLM hybrid | ❌ | ✅ (soul-agent) |
| Infrastructure | Database server | None (or cloud API) |

## API Reference

### SoulMemory

```python
from crewai_soul import SoulMemory

memory = SoulMemory(
    soul_path="SOUL.md",      # Agent identity
    memory_path="MEMORY.md",  # Memory log
    provider="anthropic",     # LLM provider for RAG
    use_hybrid=True,          # Enable RAG+RLM (default: True if soul-agent installed)
)

# Store a memory
memory.remember("We decided to use PostgreSQL.", scope="/decisions")

# Recall relevant memories
matches = memory.recall("What database did we choose?", limit=5)
for m in matches:
    print(f"[{m.score:.2f}] {m.content}")

# Clear memories (optionally by scope)
memory.forget(scope="/decisions")

# Get stats
print(memory.info())

# View structure
print(memory.tree())
```

### SchemaMemory

```python
from crewai_soul import SchemaMemory

schema = SchemaMemory(
    database_url="postgresql://...",
    llm_provider="anthropic",
)

# Generate descriptions for all tables
schema.generate()

# Or specific tables only
schema.generate(tables=["customers", "orders"])

# Get single table description
info = schema.describe("customers")

# Generate context for a query
context = schema.context_for("revenue by region")

# Export in different formats
schema.save("schema.json", format="json")
schema.save("schema.yml", format="dbt")
schema.save("training.jsonl", format="vanna")

# Full markdown documentation
docs = schema.to_markdown()
```

### SoulMateClient

```python
from crewai_soul import SoulMateClient

client = SoulMateClient(
    api_key="...",              # or SOULMATE_API_KEY env var
    base_url="...",             # or SOULMATE_URL env var
    tenant_id="...",            # for multi-tenant isolation
)

# Store memories
client.remember("Important fact", scope="/project")

# Search
results = client.recall("important", limit=10)

# Full RAG+RLM Q&A
answer = client.ask("What do we know about...")

# Clear memories
client.forget(scope="/project")

# Get stats
info = client.info()
```

## The Soul Ecosystem

crewai-soul brings together:

| Package | Purpose | PyPI |
|---------|---------|------|
| **soul-agent** | Persistent memory & identity | `pip install soul-agent` |
| **soul-schema** | Database semantic layers | `pip install soul-schema` |
| **crewai-soul** | CrewAI integration (this package) | `pip install crewai-soul` |

**SoulMate API** — Enterprise hosted service for production deployments.

## Links

- [soul.py](https://github.com/menonpg/soul.py) — Core memory library
- [soul-schema](https://github.com/menonpg/soul-schema) — Database documentation
- [SoulMate](https://menonpg.github.io/soulmate) — Enterprise offering
- [CrewAI](https://github.com/crewAIInc/crewAI) — Multi-agent framework
- [The Menon Lab](https://themenonlab.com) — Research & tools

## License

MIT
