cartesia-line 0.1.2__tar.gz → 0.1.4__tar.gz

{cartesia_line-0.1.2 → cartesia_line-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cartesia-line
-Version: 0.1.2
+Version: 0.1.4
 Summary: Cartesia Voice Agents SDK
 Author-email: "Cartesia AI, Inc." <support@cartesia.ai>
 License: Apache 2.0

{cartesia_line-0.1.2 → cartesia_line-0.1.4}/cartesia_line.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cartesia-line
-Version: 0.1.2
+Version: 0.1.4
 Summary: Cartesia Voice Agents SDK
 Author-email: "Cartesia AI, Inc." <support@cartesia.ai>
 License: Apache 2.0

{cartesia_line-0.1.2 → cartesia_line-0.1.4}/cartesia_line.egg-info/SOURCES.txt

@@ -30,10 +30,13 @@ line/tools/system_tools.py
 line/tools/tool_types.py
 line/utils/__init__.py
 line/utils/aio.py
+line/utils/dtmf_lookahead_buffer.py
 line/utils/gemini_utils.py
+line/utils/log_aiter.py
 line/utils/openai_utils.py
 line/utils/str.py
 tests/test_bridge.py
 tests/test_bus.py
+tests/test_dtmf_lookahead_buffer.py
 tests/test_routes.py
 tests/test_similarity_utils.py

{cartesia_line-0.1.2 → cartesia_line-0.1.4}/line/__init__.py

@@ -3,7 +3,6 @@
 from line.bridge import Bridge
 from line.bus import Bus, Message
 from line.call_request import CallRequest, PreCallResult
-from line.evals import AgentTurn, ConversationRunner, Turn, UserTurn
 from line.nodes.conversation_context import ConversationContext
 
 # Reasoning components
@@ -27,9 +26,4 @@ __all__ = [
     "VoiceAgentApp",
     "VoiceAgentSystem",
     "register_observability_event",
-    "AgentTurn",
-    "ConversationRunner",
-    "Turn",
-    "UserTurn",
-    "SimilarityUtils",
 ]

cartesia_line-0.1.4/line/utils/dtmf_lookahead_buffer.py

@@ -0,0 +1,128 @@
+from collections.abc import Generator
+import re
+from typing import Union
+
+from line.events import AgentResponse, DTMFOutputEvent
+
+DTMF_EXPRESSION = "dtmf="
+
+
+class DTMFLookAheadStringBuffer:
+    """
+    Wrapper ontop of DTMFLookAheadCharacterBuffer, but will yield strings instead of characters
+    """
+
+    def __init__(self):
+        self.buffer = DTMFLookAheadCharacterBuffer()
+
+    def feed(self, string: str) -> Generator[Union[AgentResponse, DTMFOutputEvent], None, None]:
+        for char in string:
+            for item in self.buffer.feed(char):
+                if isinstance(item, DTMFOutputEvent):
+                    for digit in item.button:
+                        yield DTMFOutputEvent(button=digit)
+                else:
+                    yield item
+
+    def flush(self) -> Generator[Union[AgentResponse, DTMFOutputEvent], None, None]:
+        for item in self.buffer.flush():
+            if isinstance(item, DTMFOutputEvent):
+                for digit in split_dtmf_output(item):
+                    yield digit
+            else:
+                yield item
+
+
+def split_dtmf_output(item: DTMFOutputEvent) -> Generator[DTMFOutputEvent, None, None]:
+    """
+    DTMFOutputEvent(button="12") -> [DTMFOutputEvent(button="1"), DTMFOutputEvent(button="2")]
+    """
+    for digit in item.button:
+        yield DTMFOutputEvent(button=digit)
+
+
+class DTMFLookAheadCharacterBuffer:
+    """
+    A look ahead buffer that will replace DTMF expressions with DTMF output events
+
+    Why do we have this:
+    - Sometimes, gemini will yield ["hello dtmf", "=123 world"]
+    - We want to yield [AgentResponse("hello"), DTMFOutputEvent("123"), AgentResponse("world")]
+    - This is a look ahead buffer, so we need to keep track of the buffer and the chunks
+    """
+
+    def __init__(self):
+        self.non_dtmf_buffer = ""
+        self.dtmf_buffer = ""
+
+        self.chunks = []
+
+        self.full_expression = re.compile(r"dtmf=(\d+)")
+        self.dtmf_preamble = "dtmf="
+
+    def feed(self, char: str) -> Generator[Union[AgentResponse, DTMFOutputEvent], None, None]:
+        """
+        Feed a character into the buffer and see if we yield anything
+        """
+        # new character is in a word boundary: flush
+        is_word_char = re.match(r"[\w0-9=]", char)
+        # No match and will not be a match: buffer next char onto non-dtmf buffer
+        if not self.dtmf_buffer and not self.dtmf_preamble.startswith(char):
+            self.non_dtmf_buffer += char
+            return
+
+        # No match and might be a match: buffer next char to dtmf buffer
+        if not self.dtmf_buffer and self.dtmf_preamble.startswith(char):
+            self.dtmf_buffer += char
+            return
+
+        if self.dtmf_buffer and not is_word_char:
+            # We are in a match, flush both
+            if self.dtmf_buffer.startswith(self.dtmf_preamble):
+                if self.non_dtmf_buffer:
+                    yield AgentResponse(content=self.non_dtmf_buffer)
+
+                captured = self.dtmf_buffer.replace(self.dtmf_preamble, "", 1)
+                yield DTMFOutputEvent(
+                    button=captured,
+                )
+
+            else:
+                # Otherwise, we didn't build enough in the dtmf buffer so move the buffer and then flush
+                to_flush = self.non_dtmf_buffer + self.dtmf_buffer
+                if to_flush:
+                    yield AgentResponse(content=to_flush)
+
+            # Next reset
+            self.non_dtmf_buffer = ""
+            self.dtmf_buffer = ""
+
+            # Finally, recursively feed the character back in
+            for item in self.feed(char):
+                yield item
+            return
+
+        # New character is not in a word boundary, keep accumulating and checking
+        if self.dtmf_buffer and is_word_char:
+            self.dtmf_buffer += char
+
+            return
+
+        raise RuntimeError(f"Invalid state: {char=} {self.dtmf_buffer=} {self.non_dtmf_buffer=}")
+
+    def flush(self) -> Generator[Union[AgentResponse, DTMFOutputEvent], None, None]:
+        if self.dtmf_buffer.startswith(self.dtmf_preamble):
+            captured = self.dtmf_buffer.replace(self.dtmf_preamble, "", 1)
+            if self.non_dtmf_buffer:
+                yield AgentResponse(content=self.non_dtmf_buffer)
+
+            yield DTMFOutputEvent(button=captured)
+        else:
+            content = self.non_dtmf_buffer + self.dtmf_buffer
+            if content:
+                yield AgentResponse(content=content)
+
+        # Cleanup
+        self.non_dtmf_buffer = ""
+        self.dtmf_buffer = ""
+        return

{cartesia_line-0.1.2 → cartesia_line-0.1.4}/line/utils/gemini_utils.py

@@ -11,6 +11,8 @@ from loguru import logger
 
 from line.events import (
     AgentResponse,
+    DTMFInputEvent,
+    DTMFOutputEvent,
     EventInstance,
     EventType,
     ToolResult,
@@ -65,6 +67,10 @@ def convert_messages_to_gemini(
             gemini_messages.append(types.ModelContent(parts=[types.Part.from_text(text=event.content)]))
         elif isinstance(event, UserTranscriptionReceived):
             gemini_messages.append(types.UserContent(parts=[types.Part.from_text(text=event.content)]))
+        elif isinstance(event, DTMFInputEvent):
+            gemini_messages.append(types.UserContent(parts=[types.Part.from_text(text=event.button)]))
+        elif isinstance(event, DTMFOutputEvent):
+            gemini_messages.append(types.ModelContent(parts=[types.Part.from_text(text=event.button)]))
         elif isinstance(event, ToolResult):
             # Gemini 400s if a ToolResult is the first message in the context, so don't add it:
             if not gemini_messages:

cartesia_line-0.1.4/line/utils/log_aiter.py

@@ -0,0 +1,123 @@
+from contextlib import contextmanager
+import datetime
+
+from loguru import logger
+
+
+def log_afunc(log_result=False, message=None):
+    """Decorator to log execution time of async functions
+
+    Args:
+        log_result: If True, also log the function result
+        message: Optional message to include in log statements for additional context
+    """
+
+    def decorator(func):
+        async def wrapper(*args, **kwargs):
+            # Use custom message if provided, otherwise use function name
+            log_message = message or func.__name__
+
+            logger.info(f"[START FUNC] {log_message}")
+            start_time = datetime.datetime.now()
+            try:
+                result = await func(*args, **kwargs)
+                end_time = datetime.datetime.now()
+                duration = (end_time - start_time).total_seconds()
+                logger.info(f"[END FUNC] {log_message}. elapsed_time={duration:.2f}s")
+                if log_result:
+                    logger.info(f"[RESULT FUNC] {log_message}. {result=}")
+                return result
+            except Exception as e:
+                raise e
+
+        return wrapper
+
+    return decorator
+
+
+def log_aiter_func(message=None, show_each=False):
+    """Decorator to log timing information for async generator functions
+
+    Args:
+        message: Optional message to include in log statements for additional context
+        measure_each: If True, log time between each iteration
+
+    Usage:
+        @time_aiter_func(message="Processing data", measure_each=True)
+        async def my_generator():
+            yield item
+    """
+
+    def decorator(func):
+        async def wrapper(*args, **kwargs):
+            # Use custom message if provided, otherwise use function name
+            log_message = message or func.__name__
+
+            logger.info(f"[START ITER] {log_message}")
+            start_time = datetime.datetime.now()
+            item_count = 0
+            last_time = start_time
+            iter_timings = []
+
+            try:
+                async for item in func(*args, **kwargs):
+                    current_time = datetime.datetime.now()
+                    time_since_last = (current_time - last_time).total_seconds()
+                    iter_timings.append(round(time_since_last, 2))
+
+                    if item_count == 0:
+                        logger.info(
+                            f"[FIRST_ITEM ITER] {log_message}. time_to_first_item={time_since_last:.2f}s"
+                        )
+
+                    item_count += 1
+                    last_time = current_time
+                    yield item
+            except Exception as e:
+                logger.exception(f"[ERROR] {log_message}. {e}")
+                raise e
+
+            finally:
+                end_time = datetime.datetime.now()
+                total_duration = (end_time - start_time).total_seconds()
+
+                # Use iter_timings for all timing information
+                time_to_first_item = f"{iter_timings[0]:.2f}s" if iter_timings else "0s"
+
+                displayed_timings = iter_timings if show_each else []
+
+                logger.info(
+                    f"[END ITER] {log_message}. items_yielded_count={item_count},"
+                    + f" total_time={total_duration:.2f}s, time_to_first_item={time_to_first_item},"
+                    + f" iter_timings={displayed_timings}"
+                )
+
+        return wrapper
+
+    return decorator
+
+
+@contextmanager
+def context_log(message: str):
+    """
+    Context manager that logs entry and exit messages.
+
+    Args:
+        message: The message to log (will be prefixed with [ENTER] and [EXIT])
+
+    Example:
+        with context_logger("Starting service"):
+            # do something
+    """
+    logger.info(f"[START] {message}")
+    start_time = datetime.datetime.now()
+
+    try:
+        yield
+    except Exception as e:
+        duration = (datetime.datetime.now() - start_time).total_seconds()
+        logger.exception(f"[ERROR] {message}. duration={duration:.2f}s. {e}")
+        raise
+    finally:
+        duration = (datetime.datetime.now() - start_time).total_seconds()
+        logger.info(f"[EXIT] {message}. duration={duration:.2f}s")

{cartesia_line-0.1.2 → cartesia_line-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cartesia-line"
-version = "0.1.2"
+version = "0.1.4"
 description = "Cartesia Voice Agents SDK"
 readme = "README.md"
 requires-python = ">=3.9"

cartesia_line-0.1.4/tests/test_dtmf_lookahead_buffer.py

@@ -0,0 +1,173 @@
+from line.events import AgentResponse, DTMFOutputEvent
+from line.utils.dtmf_lookahead_buffer import (
+    DTMFLookAheadCharacterBuffer,
+    DTMFLookAheadStringBuffer,
+)
+
+
+def test_dtmf_char_buffer_base_case():
+    actual = []
+    buffer = DTMFLookAheadCharacterBuffer()
+
+    actual.extend(list(buffer.feed("h")))
+    actual.extend(list(buffer.feed("e")))
+    actual.extend(list(buffer.feed("l")))
+    actual.extend(list(buffer.feed("l")))
+    actual.extend(list(buffer.feed("o")))
+
+    assert actual == []
+
+    actual = list(buffer.flush())
+    assert actual == [AgentResponse(content="hello")]
+
+
+def test_dtmf_char_buffer_dtmf_case():
+    actual = []
+    buffer = DTMFLookAheadCharacterBuffer()
+
+    actual.extend(list(buffer.feed("d")))
+    assert actual == []
+    actual.extend(list(buffer.feed("t")))
+    assert actual == []
+    actual.extend(list(buffer.feed("m")))
+    assert actual == []
+    actual.extend(list(buffer.feed("f")))
+    assert actual == []
+    actual.extend(list(buffer.feed("=")))
+
+    assert actual == []
+
+    actual.extend(list(buffer.feed("1")))
+    assert actual == []
+
+    actual.extend(list(buffer.feed("2")))
+    assert actual == []
+
+    actual.extend(list(buffer.feed(" ")))
+    assert actual == [DTMFOutputEvent(button="12")]
+
+    actual = list(buffer.flush())
+    assert actual == [AgentResponse(content=" ")]
+
+
+def test_dtmf_char_buffer_mixed_case():
+    """
+    'hello dtmf=123 dtmf=3world'
+    """
+    actual = []
+    buffer = DTMFLookAheadCharacterBuffer()
+
+    actual.extend(list(buffer.feed("h")))
+    actual.extend(list(buffer.feed("e")))
+    actual.extend(list(buffer.feed("l")))
+    actual.extend(list(buffer.feed("l")))
+    actual.extend(list(buffer.feed("o")))
+    actual.extend(list(buffer.feed(" ")))
+    actual.extend(list(buffer.feed("d")))
+    actual.extend(list(buffer.feed("t")))
+    actual.extend(list(buffer.feed("m")))
+    actual.extend(list(buffer.feed("f")))
+    actual.extend(list(buffer.feed("=")))
+    actual.extend(list(buffer.feed("1")))
+    actual.extend(list(buffer.feed("2")))
+    actual.extend(list(buffer.feed("3")))
+
+    assert actual == []
+
+    actual.extend(list(buffer.feed(" ")))
+    assert actual == [AgentResponse(content="hello "), DTMFOutputEvent(button="123")]
+
+    actual.extend(list(buffer.feed("d")))
+    actual.extend(list(buffer.feed("t")))
+    actual.extend(list(buffer.feed("m")))
+    actual.extend(list(buffer.feed("f")))
+    actual.extend(list(buffer.feed("=")))
+    actual.extend(list(buffer.feed("3")))
+    assert actual == [AgentResponse(content="hello "), DTMFOutputEvent(button="123")]
+
+    actual.extend(list(buffer.feed(" ")))
+    assert actual == [
+        AgentResponse(content="hello "),
+        DTMFOutputEvent(button="123"),
+        AgentResponse(content=" "),
+        DTMFOutputEvent(button="3"),
+    ]
+
+    actual.extend(list(buffer.feed("w")))
+    actual.extend(list(buffer.feed("o")))
+    actual.extend(list(buffer.feed("r")))
+    actual.extend(list(buffer.feed("l")))
+    actual.extend(list(buffer.feed("d")))
+    actual.extend(list(buffer.flush()))
+
+    assert actual == [
+        AgentResponse(content="hello "),
+        DTMFOutputEvent(button="123"),
+        AgentResponse(content=" "),
+        DTMFOutputEvent(button="3"),
+        AgentResponse(content=" world"),
+    ]
+
+
+def test_dtmf_string_buffer_base_case():
+    actual = []
+    buffer = DTMFLookAheadStringBuffer()
+
+    actual.extend(list(buffer.feed("hello")))
+    assert actual == []
+
+    actual.extend(list(buffer.flush()))
+    assert actual == [AgentResponse(content="hello")]
+
+
+def test_dtmf_string_buffer_dtmf_case():
+    actual = []
+    buffer = DTMFLookAheadStringBuffer()
+
+    actual.extend(list(buffer.feed("dtmf=3")))
+    assert actual == []
+
+    actual.extend(list(buffer.flush()))
+    assert actual == [DTMFOutputEvent(button="3")]
+
+
+def test_dtmf_string_buffer_mixed_case():
+    actual = []
+    buffer = DTMFLookAheadStringBuffer()
+
+    actual.extend(list(buffer.feed("hello ")))
+    actual.extend(list(buffer.feed("dtm")))
+    actual.extend(list(buffer.feed("f=123 dtmf=3 w")))
+
+    assert actual == [
+        AgentResponse(content="hello "),
+        DTMFOutputEvent(button="1"),
+        DTMFOutputEvent(button="2"),
+        DTMFOutputEvent(button="3"),
+        AgentResponse(content=" "),
+        DTMFOutputEvent(button="3"),
+    ]
+    actual.extend(list(buffer.feed("orld")))
+    actual.extend(list(buffer.flush()))
+    assert actual == [
+        AgentResponse(content="hello "),
+        DTMFOutputEvent(button="1"),
+        DTMFOutputEvent(button="2"),
+        DTMFOutputEvent(button="3"),
+        AgentResponse(content=" "),
+        DTMFOutputEvent(button="3"),
+        AgentResponse(content=" world"),
+    ]
+
+
+def test_dtmf_string_buffer_mixed_case_2():
+    actual = []
+    buffer = DTMFLookAheadStringBuffer()
+
+    actual.extend(list(buffer.feed("Hi")))
+    actual.extend(list(buffer.feed(", this is Angela calling Andrew Clement?")))
+    actual.extend(list(buffer.flush()))
+    assert [
+        AgentResponse(content="Hi, this is Angela calling Andrew"),
+        AgentResponse(content=" Clement?"),
+    ] == actual