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.
@@ -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()