primfunctions 0.1.0__tar.gz

primfunctions-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: primfunctions
+Version: 0.1.0
+Summary: Prim AI Functions
+Author-email: Prim AI <derek@primai.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: black>=23.3.0
+
+# prim-functions
+
+A comprehensive SDK for interacting with the Prim AI Functions.
+
+## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Development Setup](#development-setup)
+
+## Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+
+If you do not have a uv virtual environment, you can create one with:
+```bash
+uv venv --python 3.12
+```
+
+**Note:** We recommend using uv to install the package due to the incredible speed of the package manager. The package can still be installed via pip directly, but it will be slower.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install primfunctions
+```
+
+### From Source
+
+```bash
+uv pip install .
+```
+
+## Development Setup
+
+### Git Hooks
+This project includes git hooks to ensure code quality. To set up the git hooks:
+
+```bash
+python setup_hooks.py
+```
+
+This will create a pre-commit hook that automatically runs black on Python files before each commit.

primfunctions-0.1.0/README.md

@@ -0,0 +1,45 @@
+# prim-functions
+
+A comprehensive SDK for interacting with the Prim AI Functions.
+
+## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Development Setup](#development-setup)
+
+## Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+
+If you do not have a uv virtual environment, you can create one with:
+```bash
+uv venv --python 3.12
+```
+
+**Note:** We recommend using uv to install the package due to the incredible speed of the package manager. The package can still be installed via pip directly, but it will be slower.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install primfunctions
+```
+
+### From Source
+
+```bash
+uv pip install .
+```
+
+## Development Setup
+
+### Git Hooks
+This project includes git hooks to ensure code quality. To set up the git hooks:
+
+```bash
+python setup_hooks.py
+```
+
+This will create a pre-commit hook that automatically runs black on Python files before each commit.

primfunctions-0.1.0/primfunctions/configuration.py

@@ -0,0 +1,47 @@
+from enum import Enum
+
+
+class LLMProvider(Enum):
+    OPENAI = "openai"
+    GEMINI = "gemini"
+
+
+class Configuration:
+    def __init__(
+        self,
+        input_type: str = "mic",
+        default_voice: str = "nova",
+        llm_provider: LLMProvider = LLMProvider.OPENAI,
+        stt_model: str = "nova-3",
+        stt_prompt: str = "",
+        stt_endpointing: int = 300,
+        recording_enabled: bool = False,
+        timeout: int = 5,
+    ):
+        self.input_type = input_type
+        self.default_voice = default_voice
+        self.stt_model = stt_model
+        self.stt_prompt = stt_prompt
+        self.stt_endpointing = stt_endpointing
+        self.recording_enabled = recording_enabled
+        self.timeout = timeout
+
+        if isinstance(llm_provider, str):
+            self.llm_provider = LLMProvider(llm_provider)
+        else:
+            self.llm_provider = llm_provider
+
+    def set_llm_provider(self, llm_provider: LLMProvider):
+        self.llm_provider = llm_provider
+
+    def __dict__(self):
+        return {
+            "input_type": self.input_type,
+            "default_voice": self.default_voice,
+            "llm_provider": self.llm_provider.value,
+            "stt_model": self.stt_model,
+            "stt_prompt": self.stt_prompt,
+            "stt_endpointing": self.stt_endpointing,
+            "recording_enabled": self.recording_enabled,
+            "timeout": self.timeout,
+        }

primfunctions-0.1.0/primfunctions/context.py

@@ -0,0 +1,128 @@
+from typing import List, Dict, Any
+
+from .configuration import Configuration, LLMProvider
+
+
+class Context:
+    def __init__(
+        self,
+        agent_id: str = "",
+        environment: str = "",
+        session_id: str = "",
+        configuration: Configuration = Configuration(),
+        data: dict = {},
+        variables: dict = {},
+    ):
+        self.agent_id = agent_id
+        self.environment = environment
+        self.session_id = session_id
+        self.configuration = configuration
+        self.data = data
+        self.variables = variables
+        self.history = []
+
+    def serialize(self) -> dict:
+        return {
+            "agent_id": self.agent_id,
+            "environment": self.environment,
+            "session_id": self.session_id,
+            "configuration": self.configuration.__dict__(),
+            "data": self.data,
+            "history": self.history,
+            "variables": self.variables,
+        }
+
+    def deserialize(self, state: dict):
+        self.agent_id = state.get("agent_id", self.agent_id)
+        self.environment = state.get("environment", self.environment)
+        self.session_id = state.get("session_id", self.session_id)
+        self.configuration = Configuration(
+            **state.get("configuration", self.configuration.__dict__())
+        )
+        self.data = state.get("data", self.data)
+        self.history = state.get("history", self.history)
+        self.variables = state.get("variables", self.variables)
+
+    def set_data(self, key: str, value: Any):
+        self.data[key] = value
+
+    def get_data(self, key: str, default: Any = None):
+        return self.data.get(key, default)
+
+    # Backward compatible methods - these work with OpenAI format internally
+    def add_system_message(self, message: str):
+        """Add system message. For Gemini, this will be converted when getting formatted history."""
+        self.history.append({"role": "system", "content": message})
+
+    def add_assistant_message(self, message: str):
+        """Add assistant message. For Gemini, this will be converted to 'model' role when getting formatted history."""
+        self.history.append({"role": "assistant", "content": message})
+
+    def add_user_message(self, message: str):
+        """Add user message. Works the same for both OpenAI and Gemini."""
+        self.history.append({"role": "user", "content": message})
+
+    # New generic methods for flexibility
+    def add_message(self, role: str, content: str):
+        """Generic method to add any message with specified role."""
+        self.history.append({"role": role, "content": content})
+
+    def get_history(self, turns: int = 0) -> List[Dict[str, str]]:
+        """Get history in original OpenAI format for backward compatibility."""
+        if turns == 0:
+            return self.history
+        return self.history[-(turns * 2) :]
+
+    def get_history_message(self, turns: int = 0) -> List[Dict[str, str]]:
+        """Get history formatted for the current model provider."""
+        history = self.get_history(turns)
+
+        if self.configuration.llm_provider == LLMProvider.OPENAI:
+            return history
+        elif self.configuration.llm_provider == LLMProvider.GEMINI:
+            return self._convert_to_gemini_format(history)
+        else:
+            return history
+
+    def _convert_to_gemini_format(
+        self, history: List[Dict[str, str]]
+    ) -> List[Dict[str, str]]:
+        """Convert OpenAI format to Gemini format."""
+        converted = []
+        system_messages = []
+
+        for message in history:
+            role = message["role"]
+            content = message["content"]
+
+            if role == "system":
+                # Collect system messages to prepend to first user message
+                system_messages.append(content)
+            elif role == "assistant":
+                # Convert assistant to model for Gemini
+                converted.append({"role": "model", "content": content})
+            elif role == "user":
+                # If we have accumulated system messages, prepend them to this user message
+                if system_messages:
+                    system_context = "\n".join(system_messages)
+                    content = f"System: {system_context}\n\nUser: {content}"
+                    system_messages = []  # Clear after using
+                converted.append({"role": "user", "content": content})
+            else:
+                # Unknown role, keep as is
+                converted.append(message)
+
+        # If there are remaining system messages at the end, add them as a user message
+        if system_messages:
+            system_content = "\n".join(system_messages)
+            converted.append({"role": "user", "content": f"System: {system_content}"})
+
+        return converted
+
+    def set_llm_provider(self, provider: LLMProvider):
+        """Change the llm provider for this context."""
+        self.configuration.llm_provider = provider
+
+    def get_llm_provider(self) -> LLMProvider:
+        """Get the current llm provider."""
+        return self.configuration.llm_provider

primfunctions-0.1.0/primfunctions/events.py

@@ -0,0 +1,145 @@
+import json
+
+
+class Event:
+    def __init__(self, name: str, data: dict = {}):
+        self.name = name
+        self.data = data
+
+
+class CustomEvent(Event):
+    def __init__(self, name: str, data: dict = {}):
+        super().__init__(name, {**data, "custom": True})
+
+
+class StartEvent(Event):
+    def __init__(self):
+        super().__init__("start")
+
+
+class StopEvent(Event):
+    def __init__(self):
+        super().__init__("stop")
+
+
+class InterruptEvent(Event):
+    def __init__(self):
+        super().__init__("interrupt")
+
+
+class TimeoutEvent(Event):
+    def __init__(self):
+        super().__init__("timeout")
+
+
+class TextEvent(Event):
+    def __init__(self, source: str, text: str):
+        super().__init__("text", {"source": source, "text": text})
+
+
+class TextToSpeechEvent(Event):
+    def __init__(self, text: str, voice="nova", cache=True, interruptable=True):
+        super().__init__(
+            "text_to_speech",
+            {
+                "text": text,
+                "voice": voice,
+                "cache": cache,
+                "interruptable": interruptable,
+            },
+        )
+
+
+class AudioEvent(Event):
+    def __init__(self, path: str):
+        super().__init__("audio", {"path": path})
+
+
+class SilenceEvent(Event):
+    def __init__(self, duration: int):
+        super().__init__("silence", {"duration": duration})
+
+
+class TransferCallEvent(Event):
+    def __init__(self, phone_number: str):
+        super().__init__("transfer_call", {"phone_number": phone_number})
+
+
+class WarmTransferEvent(Event):
+    def __init__(self, phone_number: str, data: dict):
+        super().__init__("warm_transfer", {"phone_number": phone_number, "data": data})
+
+
+class MergeCallEvent(Event):
+    def __init__(self, call_sid: str):
+        super().__init__("merge_call", {"call_sid": call_sid})
+
+
+class ContextUpdateEvent(Event):
+    def __init__(self, context: dict):
+        super().__init__("context", {"context": context})
+
+
+class ErrorEvent(Event):
+    def __init__(self, message: str):
+        super().__init__("error", {"message": message})
+
+
+class LogEvent(Event):
+    def __init__(self, message: str):
+        super().__init__("log", {"message": message})
+
+
+class CollectPaymentEvent(Event):
+    def __init__(self, amount: float):
+        super().__init__("collect_payment", {"amount": amount})
+
+
+class CollectPaymentSuccessEvent(Event):
+    def __init__(self):
+        super().__init__("collect_payment_success")
+
+
+class AddSupervisorContextEvent(Event):
+    def __init__(self, context: str):
+        super().__init__("add_supervisor_context", {"context": context})
+
+
+def event_to_str(event: Event) -> str:
+    return json.dumps({"name": event.name, "data": event.data})
+
+
+def event_from_str(event_str: str) -> Event:
+    event = json.loads(event_str)
+    name = event["name"]
+    data = event["data"]
+
+    event_types = {
+        "audio": lambda: AudioEvent(data["path"]),
+        "context": lambda: ContextUpdateEvent(data["context"]),
+        "error": lambda: ErrorEvent(data["message"]),
+        "interrupt": InterruptEvent,
+        "log": lambda: LogEvent(data["message"]),
+        "merge_call": lambda: MergeCallEvent(data["call_sid"]),
+        "silence": lambda: SilenceEvent(data["duration"]),
+        "start": StartEvent,
+        "stop": StopEvent,
+        "text_to_speech": lambda: TextToSpeechEvent(data["text"], data["voice"]),
+        "text": lambda: TextEvent(data["source"], data["text"]),
+        "timeout": TimeoutEvent,
+        "transfer_call": lambda: TransferCallEvent(data["phone_number"]),
+        "warm_transfer": lambda: WarmTransferEvent(data["phone_number"], data["data"]),
+        "collect_payment": lambda: CollectPaymentEvent(data["amount"]),
+        "collect_payment_success": CollectPaymentSuccessEvent,
+    }
+
+    if name in event_types:
+        return event_types[name]()
+
+    raise ValueError(f"Unknown event type: {name}")
+
+
+def format_event(event: Event) -> bytes:
+    event_string = event_to_str(event)
+
+    return bytes(f"{event_string}\n", "utf-8")

primfunctions-0.1.0/primfunctions/utils/streaming.py

@@ -0,0 +1,193 @@
+# Helper function to handle streaming response and chunking
+async def stream_sentences(streaming_response, punctuation_marks=None, clean_text=True):
+    """
+    Streams OpenAI or Google Gemini response and yields complete sentences as strings.
+
+    Args:
+        streaming_response: The streaming response from OpenAI or Google Gemini
+        punctuation_marks: Optional set of punctuation marks to use for sentence boundaries
+                          Defaults to ['.', '!', '?', '\n']
+        clean_text: Whether to clean markdown and special characters for speech
+                   Defaults to True
+
+    Yields:
+        str: Complete sentences as they are formed
+    """
+    import asyncio
+
+    if punctuation_marks is None:
+        punctuation_marks = [".", "!", "?", "\n"]
+
+    sentence_buffer = ""
+
+    # Check if this is an async iterator (OpenAI) or sync iterator (Gemini)
+    if hasattr(streaming_response, "__aiter__"):
+        # OpenAI async streaming
+        async for chunk in streaming_response:
+            tool_calls = _extract_tool_calls_from_chunk(chunk)
+            if tool_calls:
+                yield {"tool_calls": tool_calls}
+
+            content = _extract_content_from_chunk(chunk)
+
+            if content:
+                sentence_buffer += content
+
+                # Check if we have a complete sentence (ends with punctuation)
+                if any(punct in sentence_buffer for punct in punctuation_marks):
+                    # Find the last sentence boundary
+                    last_sentence_end = max(
+                        (sentence_buffer.rfind(punct) for punct in punctuation_marks),
+                        default=-1,
+                    )
+
+                    if last_sentence_end != -1:
+                        # Extract complete sentences
+                        complete_sentences = sentence_buffer[: last_sentence_end + 1]
+                        # Keep remaining text in buffer
+                        sentence_buffer = sentence_buffer[last_sentence_end + 1 :]
+
+                        # Clean and yield complete sentences
+                        if clean_text:
+                            complete_sentences = _clean_text_for_speech(
+                                complete_sentences
+                            )
+                        yield {"content": complete_sentences}
+    else:
+        # Gemini sync streaming - wrap in async to prevent blocking
+        for chunk in streaming_response:
+            content = _extract_content_from_chunk(chunk)
+
+            if content:
+                sentence_buffer += content
+
+                # Check if we have a complete sentence (ends with punctuation)
+                if any(punct in sentence_buffer for punct in punctuation_marks):
+                    # Find the last sentence boundary
+                    last_sentence_end = max(
+                        (sentence_buffer.rfind(punct) for punct in punctuation_marks),
+                        default=-1,
+                    )
+
+                    if last_sentence_end != -1:
+                        # Extract complete sentences
+                        complete_sentences = sentence_buffer[: last_sentence_end + 1]
+                        # Keep remaining text in buffer
+                        sentence_buffer = sentence_buffer[last_sentence_end + 1 :]
+
+                        # Clean and yield complete sentences
+                        if clean_text:
+                            complete_sentences = _clean_text_for_speech(
+                                complete_sentences
+                            )
+                        yield {"content": complete_sentences}
+
+            # Yield control to prevent blocking the event loop
+            await asyncio.sleep(0)
+
+    # Handle any remaining text in buffer
+    if sentence_buffer.strip():
+        if clean_text:
+            sentence_buffer = _clean_text_for_speech(sentence_buffer)
+        yield {"content": sentence_buffer}
+
+
+def _extract_tool_calls_from_chunk(chunk):
+    if hasattr(chunk, "choices") and chunk.choices:
+        if hasattr(chunk.choices[0], "delta") and hasattr(
+            chunk.choices[0].delta, "tool_calls"
+        ):
+            return chunk.choices[0].delta.tool_calls or ""
+    return ""
+
+
+def _extract_content_from_chunk(chunk):
+    """
+    Extract content from streaming chunk, supporting OpenAI and Direct Gemini API formats only.
+
+    Args:
+        chunk: The streaming chunk from either OpenAI or Google Gemini (direct API)
+
+    Returns:
+        str: The content text from the chunk, or empty string if no content
+    """
+    # OpenAI format: chunk.choices[0].delta.content
+    if hasattr(chunk, "choices") and chunk.choices:
+        if hasattr(chunk.choices[0], "delta") and hasattr(
+            chunk.choices[0].delta, "content"
+        ):
+            return chunk.choices[0].delta.content or ""
+
+    # Google Gemini Direct API format: chunk.text
+    if hasattr(chunk, "text"):
+        return chunk.text or ""
+
+    return ""
+
+
+def _clean_text_for_speech(text):
+    """
+    Clean text for better speech synthesis by removing/replacing problematic characters.
+
+    Args:
+        text: The text to clean
+
+    Returns:
+        str: Cleaned text suitable for speech synthesis
+    """
+    import re
+
+    if not text:
+        return text
+
+    # Remove markdown formatting
+    text = re.sub(r"\*\*(.*?)\*\*", r"\1", text)  # **bold** -> bold
+    text = re.sub(r"\*(.*?)\*", r"\1", text)  # *italic* -> italic
+    text = re.sub(r"__(.*?)__", r"\1", text)  # __bold__ -> bold
+    text = re.sub(r"_(.*?)_", r"\1", text)  # _italic_ -> italic
+    text = re.sub(r"~~(.*?)~~", r"\1", text)  # ~~strikethrough~~ -> strikethrough
+    text = re.sub(r"`(.*?)`", r"\1", text)  # `code` -> code
+
+    # Remove markdown headers
+    text = re.sub(r"^#{1,6}\s*", "", text, flags=re.MULTILINE)  # # Header -> Header
+
+    # Replace common symbols with spoken equivalents
+    replacements = {
+        "#": "hashtag ",
+        "@": "at ",
+        "&": "and ",
+        "%": "percent ",
+        "$": "dollar ",
+        "+": "plus ",
+        "=": "equals ",
+        "<": "less than ",
+        ">": "greater than ",
+        "|": "pipe ",
+        "\\": "backslash ",
+        "/": "slash ",
+        "^": "caret ",
+        "~": "tilde ",
+    }
+
+    for symbol, replacement in replacements.items():
+        text = text.replace(symbol, replacement)
+
+    # Remove brackets and their content (often contains technical info)
+    text = re.sub(r"\[.*?\]", "", text)  # [link text] ->
+    text = re.sub(r"\{.*?\}", "", text)  # {code} ->
+
+    # Clean up URLs (replace with "link")
+    text = re.sub(r"https?://\S+", "link", text)
+    text = re.sub(r"www\.\S+", "link", text)
+
+    # Clean up email addresses
+    text = re.sub(r"\S+@\S+\.\S+", "email address", text)
+
+    # Clean up multiple spaces and newlines
+    text = re.sub(r"\s+", " ", text)  # Multiple spaces -> single space
+    text = re.sub(r"\n+", ". ", text)  # Multiple newlines -> period space
+
+    # Remove leading/trailing whitespace
+    text = text.strip()
+
+    return text

primfunctions-0.1.0/primfunctions.egg-info/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: primfunctions
+Version: 0.1.0
+Summary: Prim AI Functions
+Author-email: Prim AI <derek@primai.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: black>=23.3.0
+
+# prim-functions
+
+A comprehensive SDK for interacting with the Prim AI Functions.
+
+## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Development Setup](#development-setup)
+
+## Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+
+If you do not have a uv virtual environment, you can create one with:
+```bash
+uv venv --python 3.12
+```
+
+**Note:** We recommend using uv to install the package due to the incredible speed of the package manager. The package can still be installed via pip directly, but it will be slower.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install primfunctions
+```
+
+### From Source
+
+```bash
+uv pip install .
+```
+
+## Development Setup
+
+### Git Hooks
+This project includes git hooks to ensure code quality. To set up the git hooks:
+
+```bash
+python setup_hooks.py
+```
+
+This will create a pre-commit hook that automatically runs black on Python files before each commit.

primfunctions-0.1.0/primfunctions.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+primfunctions/__init__.py
+primfunctions/configuration.py
+primfunctions/context.py
+primfunctions/events.py
+primfunctions.egg-info/PKG-INFO
+primfunctions.egg-info/SOURCES.txt
+primfunctions.egg-info/dependency_links.txt
+primfunctions.egg-info/requires.txt
+primfunctions.egg-info/top_level.txt
+primfunctions/utils/__init__.py
+primfunctions/utils/streaming.py

primfunctions-0.1.0/primfunctions.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

primfunctions-0.1.0/primfunctions.egg-info/requires.txt

@@ -0,0 +1 @@
+black>=23.3.0

primfunctions-0.1.0/primfunctions.egg-info/top_level.txt

@@ -0,0 +1 @@
+primfunctions

primfunctions-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "primfunctions"
+version = "0.1.0"
+description = "Prim AI Functions"
+authors = [
+    { name = "Prim AI", email = "derek@primai.com" }
+]
+readme = "README.md"
+requires-python = ">=3.7"
+dependencies = [
+    "black>=23.3.0"
+]

primfunctions-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+