smaran-pipecat 0.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- smaran_pipecat-0.1.1/.gitignore +73 -0
- smaran_pipecat-0.1.1/PKG-INFO +159 -0
- smaran_pipecat-0.1.1/README.md +129 -0
- smaran_pipecat-0.1.1/pyproject.toml +76 -0
- smaran_pipecat-0.1.1/src/smaran_pipecat/__init__.py +40 -0
- smaran_pipecat-0.1.1/src/smaran_pipecat/exceptions.py +29 -0
- smaran_pipecat-0.1.1/src/smaran_pipecat/service.py +223 -0
- smaran_pipecat-0.1.1/src/smaran_pipecat/utils.py +24 -0
- smaran_pipecat-0.1.1/tests/__init__.py +1 -0
- smaran_pipecat-0.1.1/tests/test_service.py +80 -0
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
|
|
2
|
+
|
|
3
|
+
# Dependencies
|
|
4
|
+
node_modules/
|
|
5
|
+
.pnp
|
|
6
|
+
.pnp.js
|
|
7
|
+
.bun/
|
|
8
|
+
|
|
9
|
+
# Local env files
|
|
10
|
+
.env
|
|
11
|
+
.env.local
|
|
12
|
+
.env.development.local
|
|
13
|
+
.env.test.local
|
|
14
|
+
.env.production.local
|
|
15
|
+
.sentryclirc
|
|
16
|
+
drizzle.config.ts
|
|
17
|
+
|
|
18
|
+
# Testing
|
|
19
|
+
coverage/
|
|
20
|
+
|
|
21
|
+
# Turbo & Monorepo
|
|
22
|
+
.turbo/
|
|
23
|
+
|
|
24
|
+
# Vercel & Cloudflare
|
|
25
|
+
.vercel/
|
|
26
|
+
.wrangler/
|
|
27
|
+
.mf/
|
|
28
|
+
|
|
29
|
+
# Web Build Outputs
|
|
30
|
+
.next/
|
|
31
|
+
out/
|
|
32
|
+
build/
|
|
33
|
+
dist/
|
|
34
|
+
.open-next/
|
|
35
|
+
|
|
36
|
+
# Rust & WebAssembly Build Outputs
|
|
37
|
+
target/
|
|
38
|
+
pkg/
|
|
39
|
+
**/*.rs.bk
|
|
40
|
+
|
|
41
|
+
# Machine Learning Models & Heavy Data
|
|
42
|
+
models/
|
|
43
|
+
!/packages/models/
|
|
44
|
+
*.onnx
|
|
45
|
+
*.bin
|
|
46
|
+
*.h5
|
|
47
|
+
*.pb
|
|
48
|
+
*.pt
|
|
49
|
+
*.pth
|
|
50
|
+
*.safetensors
|
|
51
|
+
packages/benchmark/results/
|
|
52
|
+
packages/benchmark/data/
|
|
53
|
+
|
|
54
|
+
# Python & Scripts
|
|
55
|
+
__pycache__/
|
|
56
|
+
*.pyc
|
|
57
|
+
.venv/
|
|
58
|
+
venv/
|
|
59
|
+
env/
|
|
60
|
+
.arch
|
|
61
|
+
.claude
|
|
62
|
+
|
|
63
|
+
# Debug Logs
|
|
64
|
+
npm-debug.log*
|
|
65
|
+
yarn-debug.log*
|
|
66
|
+
yarn-error.log*
|
|
67
|
+
pnpm-debug.log*
|
|
68
|
+
bun-debug.log*
|
|
69
|
+
|
|
70
|
+
# OS Misc
|
|
71
|
+
.DS_Store
|
|
72
|
+
*.pem
|
|
73
|
+
Thumbs.db
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: smaran-pipecat
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Smaran integration for Pipecat - memory-enhanced conversational AI pipelines
|
|
5
|
+
Project-URL: Homepage, https://github.com/Ayushpani/smaran
|
|
6
|
+
Project-URL: Repository, https://github.com/Ayushpani/smaran
|
|
7
|
+
Author-email: Ayush Panigrahi <ayushpanigrahi84@gmail.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
Keywords: conversational-ai,llm,memory,pipecat,smaran,voice-ai
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Requires-Dist: loguru>=0.7.3
|
|
20
|
+
Requires-Dist: pipecat-ai>=1.0.0
|
|
21
|
+
Requires-Dist: pydantic>=2.10.0
|
|
22
|
+
Requires-Dist: smaran>=0.1.0
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: black>=24.8.0; extra == 'dev'
|
|
25
|
+
Requires-Dist: isort>=5.13.2; extra == 'dev'
|
|
26
|
+
Requires-Dist: mypy>=1.14.1; extra == 'dev'
|
|
27
|
+
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
|
|
28
|
+
Requires-Dist: pytest>=8.3.5; extra == 'dev'
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# Smaran Pipecat SDK
|
|
32
|
+
|
|
33
|
+
Memory-enhanced conversational AI pipelines with [Smaran](https://github.com/Ayushpani/smaran) and [Pipecat](https://github.com/pipecat-ai/pipecat).
|
|
34
|
+
|
|
35
|
+
## Installation
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pip install smaran-pipecat
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Quick Start
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
import os
|
|
45
|
+
from pipecat.pipeline.pipeline import Pipeline
|
|
46
|
+
from smaran_pipecat import SmaranPipecatService
|
|
47
|
+
|
|
48
|
+
# Create memory service
|
|
49
|
+
memory = SmaranPipecatService(
|
|
50
|
+
api_key=os.getenv("SMARAN_API_KEY"),
|
|
51
|
+
base_url=os.getenv("SMARAN_URL"),
|
|
52
|
+
user_id="user-123",
|
|
53
|
+
session_id="conversation-456", # Optional: groups saved memories by session
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
# Add to Pipecat pipeline
|
|
57
|
+
pipeline = Pipeline([
|
|
58
|
+
transport.input(),
|
|
59
|
+
stt,
|
|
60
|
+
context_aggregator.user(),
|
|
61
|
+
memory, # Automatically recalls and injects relevant memories
|
|
62
|
+
llm,
|
|
63
|
+
transport.output(),
|
|
64
|
+
context_aggregator.assistant(),
|
|
65
|
+
])
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Configuration
|
|
69
|
+
|
|
70
|
+
### Parameters
|
|
71
|
+
|
|
72
|
+
| Parameter | Type | Required | Description |
|
|
73
|
+
| ------------ | ----------- | -------- | ----------------------------------------------------- |
|
|
74
|
+
| `user_id` | str | **Yes** | User identifier memories are scoped to |
|
|
75
|
+
| `session_id` | str | No | Session/conversation ID for grouping saved memories |
|
|
76
|
+
| `api_key` | str | No | Smaran API key (or set `SMARAN_API_KEY` env var) |
|
|
77
|
+
| `base_url` | str | No | Smaran API base URL (or set `SMARAN_URL` env var) |
|
|
78
|
+
| `params` | InputParams | No | Advanced configuration |
|
|
79
|
+
|
|
80
|
+
### Advanced Configuration
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from smaran_pipecat import SmaranPipecatService
|
|
84
|
+
|
|
85
|
+
memory = SmaranPipecatService(
|
|
86
|
+
user_id="user-123",
|
|
87
|
+
session_id="conv-456",
|
|
88
|
+
params=SmaranPipecatService.InputParams(
|
|
89
|
+
search_limit=5, # Max memories to recall per turn
|
|
90
|
+
system_prompt="Based on previous conversations, I recall:\n\n",
|
|
91
|
+
inject_mode="auto", # "auto", "system", or "user"
|
|
92
|
+
save_memory=True, # Save new memories after each turn
|
|
93
|
+
),
|
|
94
|
+
)
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## How It Works
|
|
98
|
+
|
|
99
|
+
1. **Intercepts context frames** — listens for `LLMContextFrame` in the pipeline
|
|
100
|
+
2. **Recalls memories** — queries Smaran's `/v1/recall` API with the user's latest message
|
|
101
|
+
3. **Injects memories** — formats recalled facts and adds them to the LLM context
|
|
102
|
+
4. **Saves messages** — sends new user/assistant turns to Smaran's `/v1/memories` API in the background, non-blocking
|
|
103
|
+
|
|
104
|
+
## Full Example
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
import asyncio
|
|
108
|
+
import os
|
|
109
|
+
from fastapi import FastAPI, WebSocket
|
|
110
|
+
from pipecat.pipeline.pipeline import Pipeline
|
|
111
|
+
from pipecat.pipeline.task import PipelineTask
|
|
112
|
+
from pipecat.pipeline.runner import PipelineRunner
|
|
113
|
+
from pipecat.processors.aggregators.llm_context import LLMContext, LLMContextAggregatorPair
|
|
114
|
+
from pipecat.transports.websocket.fastapi import (
|
|
115
|
+
FastAPIWebsocketTransport,
|
|
116
|
+
FastAPIWebsocketParams,
|
|
117
|
+
)
|
|
118
|
+
from smaran_pipecat import SmaranPipecatService
|
|
119
|
+
|
|
120
|
+
app = FastAPI()
|
|
121
|
+
|
|
122
|
+
@app.websocket("/chat")
|
|
123
|
+
async def websocket_endpoint(websocket: WebSocket):
|
|
124
|
+
await websocket.accept()
|
|
125
|
+
|
|
126
|
+
transport = FastAPIWebsocketTransport(
|
|
127
|
+
websocket=websocket,
|
|
128
|
+
params=FastAPIWebsocketParams(audio_in_enabled=True, audio_out_enabled=True),
|
|
129
|
+
)
|
|
130
|
+
|
|
131
|
+
context = LLMContext([{"role": "system", "content": "You are a helpful assistant."}])
|
|
132
|
+
context_aggregator = LLMContextAggregatorPair(context)
|
|
133
|
+
|
|
134
|
+
memory = SmaranPipecatService(
|
|
135
|
+
user_id="alice",
|
|
136
|
+
session_id="session-123",
|
|
137
|
+
)
|
|
138
|
+
|
|
139
|
+
pipeline = Pipeline([
|
|
140
|
+
transport.input(),
|
|
141
|
+
context_aggregator.user(),
|
|
142
|
+
memory,
|
|
143
|
+
llm,
|
|
144
|
+
transport.output(),
|
|
145
|
+
context_aggregator.assistant(),
|
|
146
|
+
])
|
|
147
|
+
|
|
148
|
+
runner = PipelineRunner()
|
|
149
|
+
task = PipelineTask(pipeline)
|
|
150
|
+
await runner.run(task)
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Check [Pipecat's own docs](https://docs.pipecat.ai/) for the current LLM
|
|
154
|
+
service and context-aggregator setup for your provider — that surface moves
|
|
155
|
+
fast between Pipecat versions.
|
|
156
|
+
|
|
157
|
+
## License
|
|
158
|
+
|
|
159
|
+
MIT
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# Smaran Pipecat SDK
|
|
2
|
+
|
|
3
|
+
Memory-enhanced conversational AI pipelines with [Smaran](https://github.com/Ayushpani/smaran) and [Pipecat](https://github.com/pipecat-ai/pipecat).
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pip install smaran-pipecat
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
```python
|
|
14
|
+
import os
|
|
15
|
+
from pipecat.pipeline.pipeline import Pipeline
|
|
16
|
+
from smaran_pipecat import SmaranPipecatService
|
|
17
|
+
|
|
18
|
+
# Create memory service
|
|
19
|
+
memory = SmaranPipecatService(
|
|
20
|
+
api_key=os.getenv("SMARAN_API_KEY"),
|
|
21
|
+
base_url=os.getenv("SMARAN_URL"),
|
|
22
|
+
user_id="user-123",
|
|
23
|
+
session_id="conversation-456", # Optional: groups saved memories by session
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
# Add to Pipecat pipeline
|
|
27
|
+
pipeline = Pipeline([
|
|
28
|
+
transport.input(),
|
|
29
|
+
stt,
|
|
30
|
+
context_aggregator.user(),
|
|
31
|
+
memory, # Automatically recalls and injects relevant memories
|
|
32
|
+
llm,
|
|
33
|
+
transport.output(),
|
|
34
|
+
context_aggregator.assistant(),
|
|
35
|
+
])
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Configuration
|
|
39
|
+
|
|
40
|
+
### Parameters
|
|
41
|
+
|
|
42
|
+
| Parameter | Type | Required | Description |
|
|
43
|
+
| ------------ | ----------- | -------- | ----------------------------------------------------- |
|
|
44
|
+
| `user_id` | str | **Yes** | User identifier memories are scoped to |
|
|
45
|
+
| `session_id` | str | No | Session/conversation ID for grouping saved memories |
|
|
46
|
+
| `api_key` | str | No | Smaran API key (or set `SMARAN_API_KEY` env var) |
|
|
47
|
+
| `base_url` | str | No | Smaran API base URL (or set `SMARAN_URL` env var) |
|
|
48
|
+
| `params` | InputParams | No | Advanced configuration |
|
|
49
|
+
|
|
50
|
+
### Advanced Configuration
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
from smaran_pipecat import SmaranPipecatService
|
|
54
|
+
|
|
55
|
+
memory = SmaranPipecatService(
|
|
56
|
+
user_id="user-123",
|
|
57
|
+
session_id="conv-456",
|
|
58
|
+
params=SmaranPipecatService.InputParams(
|
|
59
|
+
search_limit=5, # Max memories to recall per turn
|
|
60
|
+
system_prompt="Based on previous conversations, I recall:\n\n",
|
|
61
|
+
inject_mode="auto", # "auto", "system", or "user"
|
|
62
|
+
save_memory=True, # Save new memories after each turn
|
|
63
|
+
),
|
|
64
|
+
)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## How It Works
|
|
68
|
+
|
|
69
|
+
1. **Intercepts context frames** — listens for `LLMContextFrame` in the pipeline
|
|
70
|
+
2. **Recalls memories** — queries Smaran's `/v1/recall` API with the user's latest message
|
|
71
|
+
3. **Injects memories** — formats recalled facts and adds them to the LLM context
|
|
72
|
+
4. **Saves messages** — sends new user/assistant turns to Smaran's `/v1/memories` API in the background, non-blocking
|
|
73
|
+
|
|
74
|
+
## Full Example
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
import asyncio
|
|
78
|
+
import os
|
|
79
|
+
from fastapi import FastAPI, WebSocket
|
|
80
|
+
from pipecat.pipeline.pipeline import Pipeline
|
|
81
|
+
from pipecat.pipeline.task import PipelineTask
|
|
82
|
+
from pipecat.pipeline.runner import PipelineRunner
|
|
83
|
+
from pipecat.processors.aggregators.llm_context import LLMContext, LLMContextAggregatorPair
|
|
84
|
+
from pipecat.transports.websocket.fastapi import (
|
|
85
|
+
FastAPIWebsocketTransport,
|
|
86
|
+
FastAPIWebsocketParams,
|
|
87
|
+
)
|
|
88
|
+
from smaran_pipecat import SmaranPipecatService
|
|
89
|
+
|
|
90
|
+
app = FastAPI()
|
|
91
|
+
|
|
92
|
+
@app.websocket("/chat")
|
|
93
|
+
async def websocket_endpoint(websocket: WebSocket):
|
|
94
|
+
await websocket.accept()
|
|
95
|
+
|
|
96
|
+
transport = FastAPIWebsocketTransport(
|
|
97
|
+
websocket=websocket,
|
|
98
|
+
params=FastAPIWebsocketParams(audio_in_enabled=True, audio_out_enabled=True),
|
|
99
|
+
)
|
|
100
|
+
|
|
101
|
+
context = LLMContext([{"role": "system", "content": "You are a helpful assistant."}])
|
|
102
|
+
context_aggregator = LLMContextAggregatorPair(context)
|
|
103
|
+
|
|
104
|
+
memory = SmaranPipecatService(
|
|
105
|
+
user_id="alice",
|
|
106
|
+
session_id="session-123",
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
pipeline = Pipeline([
|
|
110
|
+
transport.input(),
|
|
111
|
+
context_aggregator.user(),
|
|
112
|
+
memory,
|
|
113
|
+
llm,
|
|
114
|
+
transport.output(),
|
|
115
|
+
context_aggregator.assistant(),
|
|
116
|
+
])
|
|
117
|
+
|
|
118
|
+
runner = PipelineRunner()
|
|
119
|
+
task = PipelineTask(pipeline)
|
|
120
|
+
await runner.run(task)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Check [Pipecat's own docs](https://docs.pipecat.ai/) for the current LLM
|
|
124
|
+
service and context-aggregator setup for your provider — that surface moves
|
|
125
|
+
fast between Pipecat versions.
|
|
126
|
+
|
|
127
|
+
## License
|
|
128
|
+
|
|
129
|
+
MIT
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "smaran-pipecat"
|
|
7
|
+
version = "0.1.1"
|
|
8
|
+
description = "Smaran integration for Pipecat - memory-enhanced conversational AI pipelines"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
requires-python = ">=3.10"
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "Ayush Panigrahi", email = "ayushpanigrahi84@gmail.com" }
|
|
14
|
+
]
|
|
15
|
+
keywords = [
|
|
16
|
+
"smaran",
|
|
17
|
+
"pipecat",
|
|
18
|
+
"memory",
|
|
19
|
+
"conversational-ai",
|
|
20
|
+
"llm",
|
|
21
|
+
"voice-ai",
|
|
22
|
+
]
|
|
23
|
+
classifiers = [
|
|
24
|
+
"Development Status :: 3 - Alpha",
|
|
25
|
+
"Intended Audience :: Developers",
|
|
26
|
+
"License :: OSI Approved :: MIT License",
|
|
27
|
+
"Programming Language :: Python :: 3",
|
|
28
|
+
"Programming Language :: Python :: 3.10",
|
|
29
|
+
"Programming Language :: Python :: 3.11",
|
|
30
|
+
"Programming Language :: Python :: 3.12",
|
|
31
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
32
|
+
]
|
|
33
|
+
dependencies = [
|
|
34
|
+
"pipecat-ai>=1.0.0",
|
|
35
|
+
"smaran>=0.1.0",
|
|
36
|
+
"pydantic>=2.10.0",
|
|
37
|
+
"loguru>=0.7.3",
|
|
38
|
+
]
|
|
39
|
+
|
|
40
|
+
[project.optional-dependencies]
|
|
41
|
+
dev = [
|
|
42
|
+
"pytest>=8.3.5",
|
|
43
|
+
"pytest-asyncio>=0.24.0",
|
|
44
|
+
"mypy>=1.14.1",
|
|
45
|
+
"black>=24.8.0",
|
|
46
|
+
"isort>=5.13.2",
|
|
47
|
+
]
|
|
48
|
+
|
|
49
|
+
[project.urls]
|
|
50
|
+
Homepage = "https://github.com/Ayushpani/smaran"
|
|
51
|
+
Repository = "https://github.com/Ayushpani/smaran"
|
|
52
|
+
|
|
53
|
+
[tool.hatch.build.targets.wheel]
|
|
54
|
+
packages = ["src/smaran_pipecat"]
|
|
55
|
+
|
|
56
|
+
[tool.hatch.build.targets.sdist]
|
|
57
|
+
include = [
|
|
58
|
+
"/src",
|
|
59
|
+
"/tests",
|
|
60
|
+
"/README.md",
|
|
61
|
+
"/LICENSE",
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
[tool.black]
|
|
65
|
+
line-length = 100
|
|
66
|
+
target-version = ["py310"]
|
|
67
|
+
|
|
68
|
+
[tool.isort]
|
|
69
|
+
profile = "black"
|
|
70
|
+
line_length = 100
|
|
71
|
+
|
|
72
|
+
[tool.mypy]
|
|
73
|
+
python_version = "3.10"
|
|
74
|
+
warn_return_any = true
|
|
75
|
+
warn_unused_configs = true
|
|
76
|
+
disallow_untyped_defs = true
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""Smaran Pipecat SDK — memory-enhanced conversational AI pipelines.
|
|
2
|
+
|
|
3
|
+
Integrates Smaran's cross-session memory into Pipecat pipelines: recalls
|
|
4
|
+
relevant memories before each LLM call and saves new memories after.
|
|
5
|
+
|
|
6
|
+
Example:
|
|
7
|
+
```python
|
|
8
|
+
from smaran_pipecat import SmaranPipecatService
|
|
9
|
+
|
|
10
|
+
memory = SmaranPipecatService(
|
|
11
|
+
api_key=os.getenv("SMARAN_API_KEY"),
|
|
12
|
+
user_id="user-123",
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
pipeline = Pipeline([
|
|
16
|
+
transport.input(),
|
|
17
|
+
stt,
|
|
18
|
+
user_context,
|
|
19
|
+
memory, # Recalls and injects relevant memories automatically
|
|
20
|
+
llm,
|
|
21
|
+
transport.output(),
|
|
22
|
+
])
|
|
23
|
+
```
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from .exceptions import ConfigurationError, MemoryRetrievalError, MemoryStorageError, SmaranPipecatError
|
|
27
|
+
from .service import SmaranPipecatService
|
|
28
|
+
from .utils import format_memories_to_text, get_last_user_message
|
|
29
|
+
|
|
30
|
+
__version__ = "0.1.0"
|
|
31
|
+
|
|
32
|
+
__all__ = [
|
|
33
|
+
"SmaranPipecatService",
|
|
34
|
+
"SmaranPipecatError",
|
|
35
|
+
"ConfigurationError",
|
|
36
|
+
"MemoryRetrievalError",
|
|
37
|
+
"MemoryStorageError",
|
|
38
|
+
"get_last_user_message",
|
|
39
|
+
"format_memories_to_text",
|
|
40
|
+
]
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""Exceptions for the Smaran Pipecat integration."""
|
|
2
|
+
|
|
3
|
+
from typing import Optional
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class SmaranPipecatError(Exception):
|
|
7
|
+
"""Base exception for all Smaran Pipecat errors."""
|
|
8
|
+
|
|
9
|
+
def __init__(self, message: str, original_error: Optional[Exception] = None):
|
|
10
|
+
super().__init__(message)
|
|
11
|
+
self.message = message
|
|
12
|
+
self.original_error = original_error
|
|
13
|
+
|
|
14
|
+
def __str__(self) -> str:
|
|
15
|
+
if self.original_error:
|
|
16
|
+
return f"{self.message}: {self.original_error}"
|
|
17
|
+
return self.message
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class ConfigurationError(SmaranPipecatError):
|
|
21
|
+
"""Raised when there are configuration issues (e.g., missing API key)."""
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class MemoryRetrievalError(SmaranPipecatError):
|
|
25
|
+
"""Raised when memory recall fails."""
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class MemoryStorageError(SmaranPipecatError):
|
|
29
|
+
"""Raised when memory save fails."""
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
"""Smaran Pipecat service integration.
|
|
2
|
+
|
|
3
|
+
Provides a Pipecat FrameProcessor that recalls relevant Smaran memories
|
|
4
|
+
before each LLM call and saves new memories from the conversation after.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import asyncio
|
|
8
|
+
import os
|
|
9
|
+
import re
|
|
10
|
+
from typing import Any, Literal, Optional
|
|
11
|
+
|
|
12
|
+
from loguru import logger
|
|
13
|
+
from pydantic import BaseModel, Field
|
|
14
|
+
|
|
15
|
+
from pipecat.frames.frames import Frame, InputAudioRawFrame, LLMContextFrame
|
|
16
|
+
from pipecat.processors.aggregators.llm_context import LLMContext
|
|
17
|
+
from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
|
|
18
|
+
|
|
19
|
+
from smaran import Smaran, SmaranConfigurationError
|
|
20
|
+
|
|
21
|
+
from .exceptions import ConfigurationError, MemoryRetrievalError
|
|
22
|
+
from .utils import format_memories_to_text, get_last_user_message
|
|
23
|
+
|
|
24
|
+
# XML tags for memory injection (replacement instead of accumulation)
|
|
25
|
+
MEMORY_TAG_START = "<user_memories>"
|
|
26
|
+
MEMORY_TAG_END = "</user_memories>"
|
|
27
|
+
MEMORY_TAG_PATTERN = re.compile(r"<user_memories>.*?</user_memories>", re.DOTALL)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class SmaranPipecatService(FrameProcessor):
|
|
31
|
+
"""Memory service that integrates Smaran with Pipecat pipelines.
|
|
32
|
+
|
|
33
|
+
Intercepts message frames in the pipeline, recalls relevant memories
|
|
34
|
+
from Smaran, and injects them into the LLM context before generation.
|
|
35
|
+
|
|
36
|
+
Example:
|
|
37
|
+
```python
|
|
38
|
+
from smaran_pipecat import SmaranPipecatService
|
|
39
|
+
|
|
40
|
+
memory = SmaranPipecatService(
|
|
41
|
+
api_key=os.getenv("SMARAN_API_KEY"),
|
|
42
|
+
base_url=os.getenv("SMARAN_URL"),
|
|
43
|
+
user_id="user-123",
|
|
44
|
+
)
|
|
45
|
+
```
|
|
46
|
+
"""
|
|
47
|
+
|
|
48
|
+
class InputParams(BaseModel):
|
|
49
|
+
"""Configuration parameters for memory recall and injection."""
|
|
50
|
+
|
|
51
|
+
search_limit: int = Field(default=5, ge=1)
|
|
52
|
+
system_prompt: str = Field(default="Based on previous conversations, I recall:\n\n")
|
|
53
|
+
inject_mode: Literal["auto", "system", "user"] = Field(default="auto")
|
|
54
|
+
save_memory: bool = Field(default=True)
|
|
55
|
+
|
|
56
|
+
def __init__(
|
|
57
|
+
self,
|
|
58
|
+
*,
|
|
59
|
+
api_key: Optional[str] = None,
|
|
60
|
+
base_url: Optional[str] = None,
|
|
61
|
+
user_id: str,
|
|
62
|
+
session_id: Optional[str] = None,
|
|
63
|
+
params: Optional[InputParams] = None,
|
|
64
|
+
):
|
|
65
|
+
"""Initialize the Smaran Pipecat service.
|
|
66
|
+
|
|
67
|
+
Args:
|
|
68
|
+
api_key: Smaran API key. Falls back to the SMARAN_API_KEY env var.
|
|
69
|
+
base_url: Smaran API base URL. Falls back to the SMARAN_URL env var.
|
|
70
|
+
user_id: The user ID memories are scoped to.
|
|
71
|
+
session_id: Optional session/conversation ID for grouping memories.
|
|
72
|
+
params: Configuration parameters for memory retrieval.
|
|
73
|
+
|
|
74
|
+
Raises:
|
|
75
|
+
ConfigurationError: If required configuration is missing.
|
|
76
|
+
"""
|
|
77
|
+
super().__init__()
|
|
78
|
+
|
|
79
|
+
if not user_id:
|
|
80
|
+
raise ConfigurationError("user_id is required")
|
|
81
|
+
|
|
82
|
+
self.user_id = user_id
|
|
83
|
+
self.session_id = session_id
|
|
84
|
+
self.params = params or SmaranPipecatService.InputParams()
|
|
85
|
+
|
|
86
|
+
try:
|
|
87
|
+
self._client: Optional[Smaran] = Smaran(
|
|
88
|
+
api_key=api_key or os.getenv("SMARAN_API_KEY"),
|
|
89
|
+
base_url=base_url or os.getenv("SMARAN_URL"),
|
|
90
|
+
)
|
|
91
|
+
except SmaranConfigurationError as e:
|
|
92
|
+
raise ConfigurationError(str(e), e) from e
|
|
93
|
+
|
|
94
|
+
self._messages_sent_count: int = 0
|
|
95
|
+
self._last_query: Optional[str] = None
|
|
96
|
+
self._audio_frames_detected: bool = False
|
|
97
|
+
|
|
98
|
+
async def _retrieve_memories_text(self, query: str) -> str:
|
|
99
|
+
"""Recall memories relevant to ``query`` and format them for injection."""
|
|
100
|
+
try:
|
|
101
|
+
hits = await self._client.recall(
|
|
102
|
+
query=query,
|
|
103
|
+
user_id=self.user_id,
|
|
104
|
+
session_id=self.session_id,
|
|
105
|
+
top_k=self.params.search_limit,
|
|
106
|
+
)
|
|
107
|
+
except Exception as e:
|
|
108
|
+
logger.error(f"Error recalling memories from Smaran: {e}")
|
|
109
|
+
raise MemoryRetrievalError("Failed to recall memories", e) from e
|
|
110
|
+
|
|
111
|
+
return format_memories_to_text(hits, system_prompt=self.params.system_prompt)
|
|
112
|
+
|
|
113
|
+
async def _store_message(self, text: str) -> None:
|
|
114
|
+
"""Save a message as a new memory (non-blocking, fire-and-forget)."""
|
|
115
|
+
if not self.params.save_memory or not text:
|
|
116
|
+
return
|
|
117
|
+
try:
|
|
118
|
+
await self._client.save(text=text, user_id=self.user_id, session_id=self.session_id)
|
|
119
|
+
except Exception as e:
|
|
120
|
+
logger.error(f"Error saving memory to Smaran: {e}")
|
|
121
|
+
|
|
122
|
+
def _enhance_context_with_memories(
|
|
123
|
+
self,
|
|
124
|
+
context: LLMContext,
|
|
125
|
+
query: str,
|
|
126
|
+
memory_text: str,
|
|
127
|
+
) -> None:
|
|
128
|
+
"""Inject recalled memory text into the LLM context.
|
|
129
|
+
|
|
130
|
+
Uses XML tags to wrap memories, allowing replacement on each turn
|
|
131
|
+
instead of accumulation.
|
|
132
|
+
"""
|
|
133
|
+
if self._last_query == query:
|
|
134
|
+
return
|
|
135
|
+
self._last_query = query
|
|
136
|
+
|
|
137
|
+
if not memory_text:
|
|
138
|
+
return
|
|
139
|
+
|
|
140
|
+
tagged_memory = f"{MEMORY_TAG_START}\n{memory_text}\n{MEMORY_TAG_END}"
|
|
141
|
+
|
|
142
|
+
inject_to_system = self.params.inject_mode == "system" or (
|
|
143
|
+
self.params.inject_mode == "auto" and self._audio_frames_detected
|
|
144
|
+
)
|
|
145
|
+
|
|
146
|
+
messages = context.get_messages()
|
|
147
|
+
|
|
148
|
+
if inject_to_system:
|
|
149
|
+
system_idx = None
|
|
150
|
+
for i, msg in enumerate(messages):
|
|
151
|
+
if msg.get("role") == "system":
|
|
152
|
+
system_idx = i
|
|
153
|
+
break
|
|
154
|
+
|
|
155
|
+
if system_idx is not None:
|
|
156
|
+
existing_content = messages[system_idx].get("content", "")
|
|
157
|
+
if MEMORY_TAG_PATTERN.search(existing_content):
|
|
158
|
+
messages[system_idx]["content"] = MEMORY_TAG_PATTERN.sub(
|
|
159
|
+
tagged_memory, existing_content
|
|
160
|
+
)
|
|
161
|
+
else:
|
|
162
|
+
messages[system_idx]["content"] = f"{existing_content}\n\n{tagged_memory}"
|
|
163
|
+
else:
|
|
164
|
+
messages.insert(0, {"role": "system", "content": tagged_memory})
|
|
165
|
+
else:
|
|
166
|
+
for i in range(len(messages) - 1, -1, -1):
|
|
167
|
+
msg = messages[i]
|
|
168
|
+
if msg.get("role") == "user" and MEMORY_TAG_START in msg.get("content", ""):
|
|
169
|
+
messages.pop(i)
|
|
170
|
+
break
|
|
171
|
+
|
|
172
|
+
context.add_message({"role": "user", "content": tagged_memory})
|
|
173
|
+
|
|
174
|
+
async def process_frame(self, frame: Frame, direction: FrameDirection) -> None:
|
|
175
|
+
"""Process frames, intercepting context frames for memory integration."""
|
|
176
|
+
await super().process_frame(frame, direction)
|
|
177
|
+
|
|
178
|
+
if isinstance(frame, InputAudioRawFrame):
|
|
179
|
+
if not self._audio_frames_detected:
|
|
180
|
+
self._audio_frames_detected = True
|
|
181
|
+
await self.push_frame(frame, direction)
|
|
182
|
+
return
|
|
183
|
+
|
|
184
|
+
context = frame.context if isinstance(frame, LLMContextFrame) else None
|
|
185
|
+
|
|
186
|
+
if context:
|
|
187
|
+
try:
|
|
188
|
+
context_messages = context.get_messages()
|
|
189
|
+
latest_user_message = get_last_user_message(context_messages)
|
|
190
|
+
|
|
191
|
+
if latest_user_message:
|
|
192
|
+
try:
|
|
193
|
+
memory_text = await self._retrieve_memories_text(latest_user_message)
|
|
194
|
+
self._enhance_context_with_memories(
|
|
195
|
+
context, latest_user_message, memory_text
|
|
196
|
+
)
|
|
197
|
+
except MemoryRetrievalError as e:
|
|
198
|
+
logger.warning(f"Memory retrieval failed: {e}")
|
|
199
|
+
|
|
200
|
+
storable_messages = [
|
|
201
|
+
msg for msg in context_messages if msg["role"] in ("user", "assistant")
|
|
202
|
+
]
|
|
203
|
+
unsent_messages = storable_messages[self._messages_sent_count :]
|
|
204
|
+
|
|
205
|
+
if unsent_messages:
|
|
206
|
+
for msg in unsent_messages:
|
|
207
|
+
text = f"{msg['role']}: {msg['content']}"
|
|
208
|
+
asyncio.create_task(self._store_message(text))
|
|
209
|
+
self._messages_sent_count = len(storable_messages)
|
|
210
|
+
|
|
211
|
+
await self.push_frame(frame)
|
|
212
|
+
|
|
213
|
+
except Exception as e:
|
|
214
|
+
logger.error(f"Error processing frame: {e}")
|
|
215
|
+
await self.push_frame(frame)
|
|
216
|
+
else:
|
|
217
|
+
await self.push_frame(frame, direction)
|
|
218
|
+
|
|
219
|
+
def reset_memory_tracking(self) -> None:
|
|
220
|
+
"""Reset memory tracking state for a new conversation."""
|
|
221
|
+
self._messages_sent_count = 0
|
|
222
|
+
self._last_query = None
|
|
223
|
+
self._audio_frames_detected = False
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""Utility functions for the Smaran Pipecat integration."""
|
|
2
|
+
|
|
3
|
+
from typing import Dict, List
|
|
4
|
+
|
|
5
|
+
from smaran import MemoryHit
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def get_last_user_message(messages: List[Dict[str, str]]) -> str | None:
|
|
9
|
+
"""Extract the last user message content from a list of messages."""
|
|
10
|
+
for msg in reversed(messages):
|
|
11
|
+
if msg.get("role") == "user":
|
|
12
|
+
return msg.get("content")
|
|
13
|
+
return None
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def format_memories_to_text(
|
|
17
|
+
hits: List[MemoryHit],
|
|
18
|
+
system_prompt: str = "Based on previous conversations, I recall:\n\n",
|
|
19
|
+
) -> str:
|
|
20
|
+
"""Format recalled memories into a text block for injection into an LLM prompt."""
|
|
21
|
+
if not hits:
|
|
22
|
+
return ""
|
|
23
|
+
lines = "\n".join(f"- {hit.text}" for hit in hits)
|
|
24
|
+
return f"{system_prompt}{lines}"
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Tests for the Smaran Pipecat SDK."""
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
from unittest.mock import AsyncMock, patch
|
|
2
|
+
|
|
3
|
+
import pytest
|
|
4
|
+
from smaran import MemoryHit
|
|
5
|
+
|
|
6
|
+
from smaran_pipecat import ConfigurationError, SmaranPipecatService
|
|
7
|
+
from smaran_pipecat.utils import format_memories_to_text, get_last_user_message
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def test_requires_user_id(monkeypatch):
|
|
11
|
+
monkeypatch.setenv("SMARAN_API_KEY", "sk_test")
|
|
12
|
+
monkeypatch.setenv("SMARAN_URL", "https://example.com")
|
|
13
|
+
with pytest.raises(ConfigurationError):
|
|
14
|
+
SmaranPipecatService(user_id="")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def test_get_last_user_message():
|
|
18
|
+
messages = [
|
|
19
|
+
{"role": "system", "content": "sys"},
|
|
20
|
+
{"role": "user", "content": "first"},
|
|
21
|
+
{"role": "assistant", "content": "reply"},
|
|
22
|
+
{"role": "user", "content": "second"},
|
|
23
|
+
]
|
|
24
|
+
assert get_last_user_message(messages) == "second"
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def test_format_memories_to_text_empty():
|
|
28
|
+
assert format_memories_to_text([]) == ""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def test_format_memories_to_text_with_hits():
|
|
32
|
+
hits = [MemoryHit(text="lives in Powai", score=0.9), MemoryHit(text="likes Python", score=0.8)]
|
|
33
|
+
text = format_memories_to_text(hits)
|
|
34
|
+
assert "lives in Powai" in text
|
|
35
|
+
assert "likes Python" in text
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@pytest.mark.asyncio
|
|
39
|
+
async def test_retrieve_memories_text_calls_smaran_recall(monkeypatch):
|
|
40
|
+
monkeypatch.setenv("SMARAN_API_KEY", "sk_test")
|
|
41
|
+
monkeypatch.setenv("SMARAN_URL", "https://example.com")
|
|
42
|
+
service = SmaranPipecatService(user_id="user-123", session_id="sess-1")
|
|
43
|
+
|
|
44
|
+
with patch.object(
|
|
45
|
+
service._client, "recall", AsyncMock(return_value=[MemoryHit(text="likes TypeScript")])
|
|
46
|
+
) as mock_recall:
|
|
47
|
+
text = await service._retrieve_memories_text("what language do I like?")
|
|
48
|
+
|
|
49
|
+
mock_recall.assert_awaited_once_with(
|
|
50
|
+
query="what language do I like?",
|
|
51
|
+
user_id="user-123",
|
|
52
|
+
session_id="sess-1",
|
|
53
|
+
top_k=service.params.search_limit,
|
|
54
|
+
)
|
|
55
|
+
assert "likes TypeScript" in text
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
@pytest.mark.asyncio
|
|
59
|
+
async def test_store_message_calls_smaran_save(monkeypatch):
|
|
60
|
+
monkeypatch.setenv("SMARAN_API_KEY", "sk_test")
|
|
61
|
+
monkeypatch.setenv("SMARAN_URL", "https://example.com")
|
|
62
|
+
service = SmaranPipecatService(user_id="user-123")
|
|
63
|
+
|
|
64
|
+
with patch.object(service._client, "save", AsyncMock(return_value=True)) as mock_save:
|
|
65
|
+
await service._store_message("user: hello")
|
|
66
|
+
|
|
67
|
+
mock_save.assert_awaited_once_with(text="user: hello", user_id="user-123", session_id=None)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@pytest.mark.asyncio
|
|
71
|
+
async def test_store_message_skipped_when_save_memory_disabled(monkeypatch):
|
|
72
|
+
monkeypatch.setenv("SMARAN_API_KEY", "sk_test")
|
|
73
|
+
monkeypatch.setenv("SMARAN_URL", "https://example.com")
|
|
74
|
+
params = SmaranPipecatService.InputParams(save_memory=False)
|
|
75
|
+
service = SmaranPipecatService(user_id="user-123", params=params)
|
|
76
|
+
|
|
77
|
+
with patch.object(service._client, "save", AsyncMock()) as mock_save:
|
|
78
|
+
await service._store_message("user: hello")
|
|
79
|
+
|
|
80
|
+
mock_save.assert_not_awaited()
|