Metadata-Version: 2.4
Name: suprflo
Version: 0.1.0
Summary: Official Python SDK for Suprflo — the memory layer for AI agents.
Project-URL: Homepage, https://suprflo.com
Author: Suprflo
License: MIT
License-File: LICENSE
Keywords: agents,ai,langchain,llm,memory,rag,suprflo
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: agno
Requires-Dist: agno<2,>=1; extra == 'agno'
Provides-Extra: autogen
Requires-Dist: autogen-core>=0.4; extra == 'autogen'
Provides-Extra: crewai
Requires-Dist: crewai<1,>=0.70; extra == 'crewai'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Provides-Extra: langgraph
Requires-Dist: langgraph<1,>=0.2; extra == 'langgraph'
Provides-Extra: livekit
Requires-Dist: livekit-agents<2,>=1; extra == 'livekit'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.11; extra == 'llamaindex'
Provides-Extra: openai-agents
Requires-Dist: openai-agents<1,>=0.0.1; extra == 'openai-agents'
Provides-Extra: pipecat
Requires-Dist: pipecat-ai<2,>=1; extra == 'pipecat'
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai<1,>=0.0.1; extra == 'pydantic-ai'
Description-Content-Type: text/markdown

# Suprflo Python SDK

Official Python client for [Suprflo](https://github.com/seenabaaz/memoryG) — the
memory layer for AI agents.

## Installation

```bash
pip install suprflo
```

With the optional LangChain integration:

```bash
pip install "suprflo[langchain]"
```

## Quickstart

```python
from suprflo import MemoryClient

client = MemoryClient(api_key="sk-...")  # base_url defaults to https://api.suprflo.com

# Add a memory (a string, a {role, content} dict, or a list of either)
client.add(
    [
        {"role": "user", "content": "I'm vegetarian and allergic to peanuts"},
        {"role": "assistant", "content": "Got it — I'll keep that in mind."},
    ],
    user_id="alice",
)

# Search for relevant memories
results = client.search("what can this person eat?", user_id="alice", top_k=5)
for m in results["results"]:
    print(m["memory"], m.get("score"))

client.close()
```

`MemoryClient` also works as a context manager:

```python
with MemoryClient(api_key="sk-...") as client:
    client.add("Prefers window seats", user_id="alice")
```

### Available methods

| Method | Description |
| --- | --- |
| `add(messages, *, user_id=None, agent_id=None, run_id=None, app_id=None, metadata=None, infer=True, async_mode=False, timestamp=None)` | Add memories from a message or conversation |
| `search(query, *, top_k=10, filters=None, threshold=None, rerank=None, memory_types=None, as_of=None, user_id=None, ...)` | Semantic search |
| `get(memory_id)` | Fetch one memory |
| `get_all(*, user_id=None, agent_id=None, run_id=None, app_id=None, limit=100, offset=0, memory_types=None)` | List memories |
| `update(memory_id, data)` | Replace a memory's text |
| `delete(memory_id)` | Delete one memory |
| `delete_all(*, user_id=None, agent_id=None, run_id=None, app_id=None)` | Delete a scope of memories |
| `history(memory_id)` | Change history of a memory |
| `users()` | Distinct memory subjects |

Non-2xx responses raise `suprflo.APIError` (with `.status_code` and `.message`);
`SuprfloError` is the base exception class.

## LangChain integration

```python
from suprflo import MemoryClient
from suprflo.integrations.langchain import (
    SuprfloMemory,
    SuprfloRetriever,
    create_memory_tools,
)

client = MemoryClient(api_key="sk-...")

# 1. Drop-in conversational memory
memory = SuprfloMemory(client=client, user_id="alice", memory_key="history")

# 2. A retriever for RAG chains
retriever = SuprfloRetriever(client=client, user_id="alice", top_k=5)
docs = retriever.invoke("dietary restrictions")

# 3. Agent tools: save_memory + search_memory
tools = create_memory_tools(client, user_id="alice")
```

The integration imports `langchain-core` lazily — the base SDK works without it,
and importing the integration without LangChain installed raises a clear
`ImportError` telling you to `pip install "suprflo[langchain]"`.

## License

MIT
