solana-agent 31.1.6__tar.gz → 31.2.0__tar.gz

{solana_agent-31.1.6 → solana_agent-31.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: solana-agent
-Version: 31.1.6
+Version: 31.2.0
 Summary: AI Agents for Solana
 License: MIT
 Keywords: solana,solana ai,solana agent,ai,ai agent,ai agents
@@ -14,11 +14,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Dist: instructor (==1.11.2)
-Requires-Dist: llama-index-core (==0.13.5)
-Requires-Dist: llama-index-embeddings-openai (==0.5.0)
-Requires-Dist: logfire (==4.3.6)
-Requires-Dist: openai (==1.106.1)
+Requires-Dist: instructor (==1.11.3)
+Requires-Dist: llama-index-core (==0.14.0)
+Requires-Dist: llama-index-embeddings-openai (==0.5.1)
+Requires-Dist: logfire (==4.5.0)
+Requires-Dist: openai (==1.107.0)
 Requires-Dist: pillow (==11.3.0)
 Requires-Dist: pinecone[asyncio] (==7.3.0)
 Requires-Dist: pydantic (>=2)
@@ -26,7 +26,8 @@ Requires-Dist: pymongo (==4.14.1)
 Requires-Dist: pypdf (==6.0.0)
 Requires-Dist: rich (>=13,<14.0)
 Requires-Dist: scrubadub (==2.0.1)
-Requires-Dist: typer (==0.17.3)
+Requires-Dist: typer (==0.17.4)
+Requires-Dist: websockets (>=13,<16)
 Requires-Dist: zep-cloud (==3.4.3)
 Project-URL: Documentation, https://docs.solana-agent.com
 Project-URL: Homepage, https://solana-agent.com
@@ -52,7 +53,7 @@ Build your AI agents in three lines of code!
 ## Why?
 * Three lines of code setup
 * Simple Agent Definition
-* Fast & Streaming Responses
+* Streaming or Realtime Responses
 * Solana Integration
 * Multi-Agent Swarm
 * Multi-Modal (Images & Audio & Text)
@@ -72,7 +73,6 @@ Build your AI agents in three lines of code!
 * Tested & Secure
 * Built in Python
 * Powers [CometHeart](https://cometheart.com)
-* Powers [Solana Agent Wallet](https://solana-agent.com)
 
 ## Unique Selling Proposition (USP) - Smart Workflows
 
@@ -132,6 +132,7 @@ Smart workflows are as easy as combining your tools and prompts.
 **OpenAI**
 * [gpt-4.1](https://platform.openai.com/docs/models/gpt-4.1) (agent & router)
 * [text-embedding-3-large](https://platform.openai.com/docs/models/text-embedding-3-large) (embedding)
+* [gpt-realtime](https://platform.openai.com/docs/models/gpt-realtime) (realtime audio agent)
 * [tts-1](https://platform.openai.com/docs/models/tts-1) (audio TTS)
 * [gpt-4o-mini-transcribe](https://platform.openai.com/docs/models/gpt-4o-mini-transcribe) (audio transcription)
 
@@ -308,6 +309,36 @@ async for response in solana_agent.process("user123", audio_content, audio_input
     print(response, end="")
 ```
 
+### Realtime Audio Streaming
+
+If input and/or output is encoded (compressed) like mp4/aac then you must have `ffmpeg` installed.
+
+Due to the overhead of the router (API call) - realtime only supports a single agent setup.
+
+Realtime uses MongoDB for memory so Zep is not needed.
+
+```python
+from solana_agent import SolanaAgent
+
+solana_agent = SolanaAgent(config=config)
+
+# Example: mobile sends MP4/AAC; server encodes output to AAC
+audio_content = await audio_file.read()  # bytes
+async for audio_chunk in solana_agent.process(
+    "user123",                    # required
+    audio_content,                # required
+    realtime=True,                # optional (default False)
+    output_format="audio",        # required
+    vad=True,                     # enable VAD (optional)
+    rt_encode_input=True,         # accept compressed input (optional)
+    rt_encode_output=True,        # encode output for client (optional)
+    rt_voice="marin"              # the voice to use for interactions (optional)
+    audio_input_format="mp4",     # client transport (optional)
+    audio_output_format="aac"     # client transport (optional)
+):
+    handle_audio(audio_chunk)
+```
+
 ### Image/Text Streaming
 
 ```python

{solana_agent-31.1.6 → solana_agent-31.2.0}/README.md

@@ -17,7 +17,7 @@ Build your AI agents in three lines of code!
 ## Why?
 * Three lines of code setup
 * Simple Agent Definition
-* Fast & Streaming Responses
+* Streaming or Realtime Responses
 * Solana Integration
 * Multi-Agent Swarm
 * Multi-Modal (Images & Audio & Text)
@@ -37,7 +37,6 @@ Build your AI agents in three lines of code!
 * Tested & Secure
 * Built in Python
 * Powers [CometHeart](https://cometheart.com)
-* Powers [Solana Agent Wallet](https://solana-agent.com)
 
 ## Unique Selling Proposition (USP) - Smart Workflows
 
@@ -97,6 +96,7 @@ Smart workflows are as easy as combining your tools and prompts.
 **OpenAI**
 * [gpt-4.1](https://platform.openai.com/docs/models/gpt-4.1) (agent & router)
 * [text-embedding-3-large](https://platform.openai.com/docs/models/text-embedding-3-large) (embedding)
+* [gpt-realtime](https://platform.openai.com/docs/models/gpt-realtime) (realtime audio agent)
 * [tts-1](https://platform.openai.com/docs/models/tts-1) (audio TTS)
 * [gpt-4o-mini-transcribe](https://platform.openai.com/docs/models/gpt-4o-mini-transcribe) (audio transcription)
 
@@ -273,6 +273,36 @@ async for response in solana_agent.process("user123", audio_content, audio_input
     print(response, end="")
 ```
 
+### Realtime Audio Streaming
+
+If input and/or output is encoded (compressed) like mp4/aac then you must have `ffmpeg` installed.
+
+Due to the overhead of the router (API call) - realtime only supports a single agent setup.
+
+Realtime uses MongoDB for memory so Zep is not needed.
+
+```python
+from solana_agent import SolanaAgent
+
+solana_agent = SolanaAgent(config=config)
+
+# Example: mobile sends MP4/AAC; server encodes output to AAC
+audio_content = await audio_file.read()  # bytes
+async for audio_chunk in solana_agent.process(
+    "user123",                    # required
+    audio_content,                # required
+    realtime=True,                # optional (default False)
+    output_format="audio",        # required
+    vad=True,                     # enable VAD (optional)
+    rt_encode_input=True,         # accept compressed input (optional)
+    rt_encode_output=True,        # encode output for client (optional)
+    rt_voice="marin"              # the voice to use for interactions (optional)
+    audio_input_format="mp4",     # client transport (optional)
+    audio_output_format="aac"     # client transport (optional)
+):
+    handle_audio(audio_chunk)
+```
+
 ### Image/Text Streaming
 
 ```python

{solana_agent-31.1.6 → solana_agent-31.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "solana-agent"
-version = "31.1.6"
+version = "31.2.0"
 description = "AI Agents for Solana"
 authors = ["Bevan Hunt <bevan@bevanhunt.com>"]
 license = "MIT"
@@ -24,24 +24,25 @@ testpaths = ["tests"]
 
 [tool.poetry.dependencies]
 python = ">=3.12,<4.0"
-openai = "1.106.1"
+openai = "1.107.0"
 pydantic = ">=2"
 pymongo = "4.14.1"
 zep-cloud = "3.4.3"
-instructor = "1.11.2"
+instructor = "1.11.3"
 pinecone = { version = "7.3.0", extras = ["asyncio"] }
-llama-index-core = "0.13.5"
-llama-index-embeddings-openai = "0.5.0"
+llama-index-core = "0.14.0"
+llama-index-embeddings-openai = "0.5.1"
 pypdf = "6.0.0"
 scrubadub = "2.0.1"
-logfire = "4.3.6"
-typer = "0.17.3"
+logfire = "4.5.0"
+typer = "0.17.4"
 rich = ">=13,<14.0"
 pillow = "11.3.0"
+websockets = ">=13,<16"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.4.2"
-pytest-cov = "^6.1.1"
+pytest-cov = "^7.0.0"
 pytest-asyncio = "^1.1.0"
 pytest-mock = "^3.15.0"
 pytest-github-actions-annotate-failures = "^0.3.0"

solana_agent-31.2.0/solana_agent/adapters/ffmpeg_transcoder.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from typing import List, AsyncGenerator
+
+from solana_agent.interfaces.providers.audio import AudioTranscoder
+
+logger = logging.getLogger(__name__)
+
+
+class FFmpegTranscoder(AudioTranscoder):
+    """FFmpeg-based transcoder. Requires 'ffmpeg' binary in PATH.
+
+    This uses subprocess to stream bytes through ffmpeg for encode/decode.
+    """
+
+    async def _run_ffmpeg(
+        self, args: List[str], data: bytes
+    ) -> bytes:  # pragma: no cover
+        logger.info("FFmpeg: starting process args=%s, input_len=%d", args, len(data))
+        proc = await asyncio.create_subprocess_exec(
+            "ffmpeg",
+            *args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await proc.communicate(input=data)
+        if proc.returncode != 0:
+            err = (stderr or b"").decode("utf-8", errors="ignore")
+            logger.error("FFmpeg failed (code=%s): %s", proc.returncode, err[:2000])
+            raise RuntimeError("ffmpeg failed to transcode audio")
+        logger.info("FFmpeg: finished successfully, output_len=%d", len(stdout or b""))
+        if stderr:
+            logger.debug(
+                "FFmpeg stderr: %s", stderr.decode("utf-8", errors="ignore")[:2000]
+            )
+        return stdout
+
+    async def to_pcm16(  # pragma: no cover
+        self, audio_bytes: bytes, input_mime: str, rate_hz: int
+    ) -> bytes:
+        """Decode compressed audio to mono PCM16LE at rate_hz."""
+        logger.info(
+            "Transcode to PCM16: input_mime=%s, rate_hz=%d, input_len=%d",
+            input_mime,
+            rate_hz,
+            len(audio_bytes),
+        )
+        # Prefer to hint format for MP4/AAC; ffmpeg can still autodetect if hint is wrong.
+        hinted_format = None
+        if input_mime in ("audio/mp4", "audio/aac", "audio/m4a"):
+            hinted_format = "mp4"
+        elif input_mime in ("audio/ogg", "audio/webm"):
+            hinted_format = None  # container detection is decent here
+        elif input_mime in ("audio/wav", "audio/x-wav"):
+            hinted_format = "wav"
+
+        args = [
+            "-hide_banner",
+            "-loglevel",
+            "error",
+        ]
+        if hinted_format:
+            args += ["-f", hinted_format]
+        args += [
+            "-i",
+            "pipe:0",
+            "-acodec",
+            "pcm_s16le",
+            "-ac",
+            "1",
+            "-ar",
+            str(rate_hz),
+            "-f",
+            "s16le",
+            "pipe:1",
+        ]
+        out = await self._run_ffmpeg(args, audio_bytes)
+        logger.info("Transcoded to PCM16: output_len=%d", len(out))
+        return out
+
+    async def from_pcm16(  # pragma: no cover
+        self, pcm16_bytes: bytes, output_mime: str, rate_hz: int
+    ) -> bytes:
+        """Encode PCM16LE to desired format (currently AAC ADTS for mobile streaming)."""
+        logger.info(
+            "Encode from PCM16: output_mime=%s, rate_hz=%d, input_len=%d",
+            output_mime,
+            rate_hz,
+            len(pcm16_bytes),
+        )
+        if output_mime in ("audio/mpeg", "audio/mp3"):
+            # Encode to MP3 (often better streaming compatibility on mobile)
+            args = [
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-f",
+                "s16le",
+                "-ac",
+                "1",
+                "-ar",
+                str(rate_hz),
+                "-i",
+                "pipe:0",
+                "-c:a",
+                "libmp3lame",
+                "-b:a",
+                "128k",
+                "-f",
+                "mp3",
+                "pipe:1",
+            ]
+            out = await self._run_ffmpeg(args, pcm16_bytes)
+            logger.info(
+                "Encoded from PCM16 to %s: output_len=%d", output_mime, len(out)
+            )
+            return out
+        if output_mime in ("audio/aac", "audio/mp4", "audio/m4a"):
+            # Encode to AAC in ADTS stream; clients can play it as AAC.
+            args = [
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-f",
+                "s16le",
+                "-ac",
+                "1",
+                "-ar",
+                str(rate_hz),
+                "-i",
+                "pipe:0",
+                "-c:a",
+                "aac",
+                "-b:a",
+                "96k",
+                "-f",
+                "adts",
+                "pipe:1",
+            ]
+            out = await self._run_ffmpeg(args, pcm16_bytes)
+            logger.info(
+                "Encoded from PCM16 to %s: output_len=%d", output_mime, len(out)
+            )
+            return out
+        # Default: passthrough
+        logger.info("Encode passthrough (no change), output_len=%d", len(pcm16_bytes))
+        return pcm16_bytes
+
+    async def stream_from_pcm16(  # pragma: no cover
+        self,
+        pcm_iter: AsyncGenerator[bytes, None],
+        output_mime: str,
+        rate_hz: int,
+        read_chunk_size: int = 4096,
+    ) -> AsyncGenerator[bytes, None]:
+        """Start a single continuous encoder and stream encoded audio chunks.
+
+        - Launches one ffmpeg subprocess for the entire response.
+        - Feeds PCM16LE mono bytes from pcm_iter into stdin.
+        - Yields encoded bytes from stdout as they become available.
+        """
+        if output_mime in ("audio/mpeg", "audio/mp3"):
+            args = [
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-f",
+                "s16le",
+                "-ac",
+                "1",
+                "-ar",
+                str(rate_hz),
+                "-i",
+                "pipe:0",
+                "-c:a",
+                "libmp3lame",
+                "-b:a",
+                "128k",
+                "-f",
+                "mp3",
+                "pipe:1",
+            ]
+        elif output_mime in ("audio/aac", "audio/mp4", "audio/m4a"):
+            args = [
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-f",
+                "s16le",
+                "-ac",
+                "1",
+                "-ar",
+                str(rate_hz),
+                "-i",
+                "pipe:0",
+                "-c:a",
+                "aac",
+                "-b:a",
+                "96k",
+                "-f",
+                "adts",
+                "pipe:1",
+            ]
+        else:
+            # Passthrough streaming: just yield input
+            async for chunk in pcm_iter:
+                yield chunk
+            return
+
+        logger.info("FFmpeg(stream): starting args=%s", args)
+        proc = await asyncio.create_subprocess_exec(
+            "ffmpeg",
+            *args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        assert proc.stdin is not None and proc.stdout is not None
+
+        async def _writer():
+            try:
+                async for pcm in pcm_iter:
+                    if not pcm:
+                        continue
+                    proc.stdin.write(pcm)
+                    # Backpressure
+                    await proc.stdin.drain()
+            except asyncio.CancelledError:
+                # Swallow cancellation; stdin will be closed below.
+                pass
+            except Exception as e:
+                logger.debug("FFmpeg(stream) writer error: %s", str(e))
+            finally:
+                with contextlib.suppress(Exception):
+                    proc.stdin.close()
+
+        writer_task = asyncio.create_task(_writer())
+
+        buf = bytearray()
+        try:
+            while True:
+                data = await proc.stdout.read(read_chunk_size)
+                if not data:
+                    break
+                buf.extend(data)
+                # Emit fixed-size chunks even if read returns a larger blob
+                while len(buf) >= read_chunk_size:
+                    yield bytes(buf[:read_chunk_size])
+                    del buf[:read_chunk_size]
+            # Flush any remainder
+            if buf:
+                yield bytes(buf)
+        finally:
+            # Ensure writer is done
+            if not writer_task.done():
+                with contextlib.suppress(Exception):
+                    writer_task.cancel()
+                try:
+                    await writer_task
+                except asyncio.CancelledError:
+                    pass
+                except Exception:
+                    pass
+            # Drain remaining stderr and check return code
+            try:
+                stderr = await proc.stderr.read() if proc.stderr else b""
+                code = await proc.wait()
+                if code != 0:
+                    err = (stderr or b"").decode("utf-8", errors="ignore")
+                    logger.error(
+                        "FFmpeg(stream) failed (code=%s): %s", code, err[:2000]
+                    )
+            except Exception:
+                pass

{solana_agent-31.1.6 → solana_agent-31.2.0}/solana_agent/adapters/openai_adapter.py

@@ -56,6 +56,7 @@ class OpenAIAdapter(LLMProvider):
     """OpenAI implementation of LLMProvider with web search capabilities."""
 
     def __init__(self, api_key: str, logfire_api_key: Optional[str] = None):
+        self.api_key = api_key
         self.client = AsyncOpenAI(api_key=api_key)
 
         self.logfire = False
@@ -76,6 +77,10 @@ class OpenAIAdapter(LLMProvider):
         self.embedding_model = DEFAULT_EMBEDDING_MODEL
         self.embedding_dimensions = DEFAULT_EMBEDDING_DIMENSIONS
 
+    def get_api_key(self) -> Optional[str]:  # pragma: no cover
+        """Return the API key used to configure the OpenAI client."""
+        return getattr(self, "api_key", None)
+
     async def tts(
         self,
         text: str,