spaik-sdk 0.6.2__py3-none-any.whl

spaik_sdk/recording/conditional_recorder.py

@@ -0,0 +1,38 @@
+from enum import Enum
+from typing import Optional
+
+from spaik_sdk.recording.base_playback import BasePlayback
+from spaik_sdk.recording.base_recorder import BaseRecorder
+
+
+class ConditionalRecorderMode(Enum):
+    """Mode for ConditionalRecorder behavior."""
+
+    ALWAYS_RECORD = "always_record"
+    ALWAYS_PLAYBACK = "always_playback"
+    AUTO = "auto"
+
+
+class ConditionalRecorder:
+    """Conditional recorder that switches between recording and playback based on mode."""
+
+    def __init__(self, recorder: BaseRecorder, playback: BasePlayback, mode: ConditionalRecorderMode = ConditionalRecorderMode.AUTO):
+        self.recorder = recorder
+        self.playback = playback
+        self.mode = mode
+
+    def get_recorder(self) -> Optional[BaseRecorder]:
+        """Returns the recorder if should record, None otherwise."""
+        if self.mode == ConditionalRecorderMode.ALWAYS_RECORD:
+            return self.recorder
+        elif self.mode == ConditionalRecorderMode.AUTO and not self.playback.is_available():
+            return self.recorder
+        return None
+
+    def get_playback(self) -> Optional[BasePlayback]:
+        """Returns the playback if should playback, None otherwise."""
+        if self.mode == ConditionalRecorderMode.ALWAYS_PLAYBACK:
+            return self.playback
+        elif self.mode == ConditionalRecorderMode.AUTO and self.playback.is_available():
+            return self.playback
+        return None

spaik_sdk/recording/impl/__init__.py

@@ -0,0 +1 @@
+

spaik_sdk/recording/impl/local_playback.py

@@ -0,0 +1,76 @@
+import json
+from pathlib import Path
+from typing import Any, Dict, Iterator
+
+from spaik_sdk.recording.base_playback import BasePlayback
+
+
+class LocalPlayback(BasePlayback):
+    """Local file implementation of BasePlayback."""
+
+    def __init__(self, recording_name: str = "default", recordings_dir: str = "recordings", delay: float = 0.001):
+        super().__init__(recording_name, delay)
+        self.base_recordings_dir = Path(recordings_dir)
+        self.recordings_dir = self.base_recordings_dir / self.recording_name
+
+    def _get_streaming_file_path(self, session: int) -> Path:
+        """Get path for streaming tokens file."""
+        return self.recordings_dir / f"{session}.jsonl"
+
+    def _get_structured_file_path(self, session: int) -> Path:
+        """Get path for structured response file."""
+        return self.recordings_dir / f"{session}.json"
+
+    def _session_exists(self, session_num: int) -> bool:
+        """Check if either streaming or structured file exists for session."""
+        streaming_path = self._get_streaming_file_path(session_num)
+        structured_path = self._get_structured_file_path(session_num)
+        return streaming_path.exists() or structured_path.exists()
+
+    def is_available(self) -> bool:
+        """Check if playback data is available."""
+        return self.recordings_dir.exists() and any(self.recordings_dir.iterdir())
+
+    def _load_session_data_impl(self, session_num: int) -> Iterator[Dict[str, Any]]:
+        """Load raw data for a specific session number."""
+        streaming_path = self._get_streaming_file_path(session_num)
+        structured_path = self._get_structured_file_path(session_num)
+
+        # Check for structured response first (single response)
+        if structured_path.exists():
+            with open(structured_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                yield data
+            return
+
+        # Check for streaming tokens (.jsonl)
+        if streaming_path.exists():
+            with open(streaming_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line:  # Skip empty lines
+                        try:
+                            token_data = json.loads(line)
+                            yield token_data
+                        except json.JSONDecodeError:
+                            # Skip malformed lines
+                            continue
+            return
+
+        # No files found for this session
+        raise StopIteration(f"No data found for session {session_num}")
+
+    def peek_next_session_type(self) -> str:
+        """Peek at what type the next session will be without consuming it."""
+        if not self._session_exists(self.current_session):
+            return "none"
+
+        structured_path = self._get_structured_file_path(self.current_session)
+        if structured_path.exists():
+            return "structured"
+
+        streaming_path = self._get_streaming_file_path(self.current_session)
+        if streaming_path.exists():
+            return "streaming"
+
+        return "none"

spaik_sdk/recording/impl/local_recorder.py

@@ -0,0 +1,85 @@
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional, TextIO
+
+from spaik_sdk.recording.base_recorder import BaseRecorder
+from spaik_sdk.recording.conditional_recorder import ConditionalRecorder, ConditionalRecorderMode
+from spaik_sdk.recording.impl.local_playback import LocalPlayback
+
+
+class LocalRecorder(BaseRecorder):
+    """Local file implementation of BaseRecorder."""
+
+    def __init__(self, recording_name: str = "default", recordings_dir: str = "recordings"):
+        super().__init__(recording_name)
+        self.base_recordings_dir = Path(recordings_dir)
+        self.recordings_dir = self.base_recordings_dir / self.recording_name
+        self.recordings_dir.mkdir(parents=True, exist_ok=True)
+        self._current_file_handle: Optional[TextIO] = None
+
+    def _get_streaming_file_path(self, session: int) -> Path:
+        """Get path for streaming tokens file."""
+        return self.recordings_dir / f"{session}.jsonl"
+
+    def _get_structured_file_path(self, session: int) -> Path:
+        """Get path for structured response file."""
+        return self.recordings_dir / f"{session}.json"
+
+    def _ensure_streaming_file_open(self) -> None:
+        """Ensure the current streaming file is open for writing."""
+        if self._current_file_handle is None:
+            file_path = self._get_streaming_file_path(self.current_session)
+            self._current_file_handle = open(file_path, "a", encoding="utf-8")
+
+    def _close_current_file(self) -> None:
+        """Close the current file handle if open."""
+        if self._current_file_handle:
+            self._current_file_handle.close()
+            self._current_file_handle = None
+
+    def _record_token_impl(self, token_data: Dict[str, Any]) -> None:
+        """Record a streaming token to the current .jsonl file."""
+        self._ensure_streaming_file_open()
+        json_line = json.dumps(token_data, ensure_ascii=False)
+        if self._current_file_handle:
+            self._current_file_handle.write(json_line + "\n")
+            self._current_file_handle.flush()
+
+    def _record_structured_impl(self, data: Dict[str, Any]) -> None:
+        """Record structured response to .json file and bump session."""
+        # Close any open streaming file
+        self._close_current_file()
+
+        # Write structured data to .json file
+        file_path = self._get_structured_file_path(self.current_session)
+        with open(file_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+
+        # Immediately bump to next session
+        self.current_session += 1
+
+    def request_completed(self) -> None:
+        """Close current file and bump to next session."""
+        self._close_current_file()
+        self.current_session += 1
+
+    def get_current_session(self) -> int:
+        """Get the current session number."""
+        return self.current_session
+
+    def __del__(self):
+        """Cleanup: close any open file handles."""
+        self._close_current_file()
+
+    @classmethod
+    def create_conditional_recorder(
+        cls,
+        recording_name: str = "default",
+        recordings_dir: str = "recordings",
+        mode: ConditionalRecorderMode = ConditionalRecorderMode.AUTO,
+        delay: float = 0.001,
+    ) -> ConditionalRecorder:
+        """Create a conditional recorder with a local recorder and playback."""
+        recorder = cls(recording_name, recordings_dir)
+        playback = LocalPlayback(recording_name, recordings_dir, delay)
+        return ConditionalRecorder(recorder, playback, mode)

spaik_sdk/recording/langchain_serializer.py

@@ -0,0 +1,88 @@
+import warnings
+from typing import Any, Dict
+
+from langchain_core.load import dumpd, load
+from langchain_core.messages.base import BaseMessage
+
+
+def serialize_token_data(token_data: Any) -> Dict[str, Any]:
+    """Serialize token data that may contain LangChain objects."""
+    try:
+        # Try to serialize using LangChain's built-in serialization
+        return dumpd(token_data)
+    except Exception:
+        # Fallback: handle individual components
+        if isinstance(token_data, dict):
+            serialized = {}
+            for key, value in token_data.items():
+                try:
+                    serialized[key] = dumpd(value)
+                except Exception:
+                    # For non-serializable values, convert to string representation
+                    if isinstance(value, BaseMessage):
+                        serialized[key] = {
+                            "type": "langchain_message_fallback",
+                            "message_type": value.type,
+                            "content": value.content,
+                            "additional_kwargs": value.additional_kwargs,
+                            "id": value.id,
+                            "name": getattr(value, "name", None),
+                        }
+                    else:
+                        serialized[key] = {"type": "fallback", "data": str(value)}
+            return serialized
+        else:
+            # For non-dict objects, try to convert to string
+            return {"type": "fallback", "data": str(token_data)}
+
+
+def deserialize_token_data(data: Dict[str, Any]) -> Any:
+    """Deserialize token data that may contain LangChain objects."""
+    try:
+        # Try LangChain's built-in deserialization
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", message=".*is in beta.*")
+            return load(data)
+    except Exception:
+        # Fallback: handle individual components
+        if isinstance(data, dict):
+            deserialized = {}
+            for key, value in data.items():
+                if isinstance(value, dict):
+                    try:
+                        with warnings.catch_warnings():
+                            warnings.filterwarnings("ignore", message=".*is in beta.*")
+                            deserialized[key] = load(value)
+                    except Exception:
+                        # Check for fallback message format
+                        if value.get("type") == "langchain_message_fallback":
+                            # Reconstruct basic message info (will lose some functionality)
+                            deserialized[key] = {
+                                "type": value["message_type"],
+                                "content": value["content"],
+                                "additional_kwargs": value.get("additional_kwargs", {}),
+                                "id": value.get("id"),
+                                "name": value.get("name"),
+                            }
+                        elif value.get("type") == "fallback":
+                            deserialized[key] = value["data"]
+                        else:
+                            deserialized[key] = value
+                else:
+                    deserialized[key] = value
+            return deserialized
+        else:
+            return data
+
+
+def ensure_json_serializable(obj: Any) -> Any:
+    """Ensure an object is JSON serializable by converting problematic types."""
+    if obj is None or isinstance(obj, (str, int, float, bool)):
+        return obj
+    elif isinstance(obj, dict):
+        return {k: ensure_json_serializable(v) for k, v in obj.items()}
+    elif isinstance(obj, list):
+        return [ensure_json_serializable(item) for item in obj]
+    else:
+        # Convert other types to string
+        return str(obj)

spaik_sdk/server/__init__.py

@@ -0,0 +1 @@
+

spaik_sdk/server/api/routers/api_builder.py

@@ -0,0 +1,149 @@
+from collections.abc import Callable
+from typing import Awaitable, Optional
+
+from fastapi import APIRouter
+
+from spaik_sdk.agent.base_agent import BaseAgent
+from spaik_sdk.attachments.file_storage_provider import set_file_storage
+from spaik_sdk.attachments.storage.base_file_storage import BaseFileStorage
+from spaik_sdk.attachments.storage.impl.local_file_storage import LocalFileStorage
+from spaik_sdk.server.api.routers.audio_router_factory import AudioRouterFactory
+from spaik_sdk.server.api.routers.file_router_factory import FileRouterFactory
+from spaik_sdk.server.api.routers.thread_router_factory import ThreadRouterFactory
+from spaik_sdk.server.api.streaming.streaming_negotiator import StreamingNegotiator
+from spaik_sdk.server.authorization.base_authorizer import BaseAuthorizer
+from spaik_sdk.server.authorization.base_user import BaseUser
+from spaik_sdk.server.authorization.dummy_authorizer import DummyAuthorizer
+from spaik_sdk.server.job_processor.thread_job_processor import ThreadJobProcessor
+from spaik_sdk.server.pubsub.cancellation_publisher import CancellationPublisher
+from spaik_sdk.server.pubsub.cancellation_subscriber import CancellationSubscriber
+from spaik_sdk.server.pubsub.impl.local_cancellation_pubsub import get_local_cancellation_pubsub
+from spaik_sdk.server.queue.agent_job_queue import AgentJobQueue
+from spaik_sdk.server.response.response_generator import ResponseGenerator
+from spaik_sdk.server.response.simple_agent_response_generator import SimpleAgentResponseGenerator
+from spaik_sdk.server.services.thread_service import ThreadService
+from spaik_sdk.server.storage.base_thread_repository import BaseThreadRepository
+from spaik_sdk.server.storage.impl.in_memory_thread_repository import InMemoryThreadRepository
+from spaik_sdk.server.storage.impl.local_file_thread_repository import LocalFileThreadRepository
+
+
+class ApiBuilder:
+    def __init__(
+        self,
+        repository: BaseThreadRepository,
+        authorizer: Optional[BaseAuthorizer[BaseUser]] = None,
+        streaming_negotiator: Optional[StreamingNegotiator] = None,
+        job_queue: Optional[AgentJobQueue] = None,
+        cancellation_subscriber_provider: Optional[Callable[[str], Awaitable[CancellationSubscriber]]] = None,
+        cancellation_publisher: Optional[CancellationPublisher] = None,
+        response_generator: Optional[ResponseGenerator] = None,
+        agent: Optional[BaseAgent] = None,
+        file_storage: Optional[BaseFileStorage] = None,
+    ):
+        self.repository = repository
+        self.thread_service = ThreadService(repository)
+        self.authorizer = authorizer
+        self.streaming_negotiator = streaming_negotiator
+        self.job_queue = job_queue
+        self.cancellation_subscriber_provider = cancellation_subscriber_provider
+        self.cancellation_publisher = cancellation_publisher
+        self.file_storage = file_storage
+        if not response_generator and agent:
+            self.response_generator: Optional[ResponseGenerator] = SimpleAgentResponseGenerator(agent)
+        else:
+            self.response_generator = response_generator
+
+    def build_file_router(self) -> APIRouter:
+        if not self.file_storage:
+            raise ValueError("File storage is required for file router")
+        factory = FileRouterFactory(
+            file_storage=self.file_storage,
+            authorizer=self.authorizer,
+        )
+        return factory.create_router()
+
+    def build_audio_router(
+        self,
+        tts_model: Optional[str] = None,
+        stt_model: Optional[str] = None,
+    ) -> APIRouter:
+        """
+        Build the audio router for TTS/STT endpoints.
+
+        Args:
+            tts_model: Default TTS model (e.g., "tts-1", "gemini-2.5-flash-tts")
+            stt_model: Default STT model (e.g., "whisper-1")
+
+        Returns:
+            FastAPI router with /audio/speech and /audio/transcribe endpoints
+        """
+        factory = AudioRouterFactory(
+            authorizer=self.authorizer,
+            tts_model=tts_model,
+            stt_model=stt_model,
+        )
+        return factory.create_router()
+
+    def build_thread_router(self) -> APIRouter:
+        if not self.response_generator:
+            raise ValueError("Response generator or agent is required")
+
+        job_processor = ThreadJobProcessor(thread_service=self.thread_service, response_generator=self.response_generator)
+        factory = ThreadRouterFactory(
+            service=self.thread_service,
+            authorizer=self.authorizer,
+            streaming_negotiator=self.streaming_negotiator,
+            job_queue=self.job_queue,
+            thread_job_processor=job_processor,
+            cancellation_subscriber_provider=self.cancellation_subscriber_provider,
+            cancellation_publisher=self.cancellation_publisher,
+        )
+        return factory.create_router()
+
+    @classmethod
+    def stateful(
+        cls,
+        repository: BaseThreadRepository,
+        authorizer: BaseAuthorizer[BaseUser],
+        agent: Optional[BaseAgent] = None,
+        response_generator: Optional[ResponseGenerator] = None,
+        file_storage: Optional[BaseFileStorage] = None,
+    ) -> "ApiBuilder":
+        cancellation_pubsub = get_local_cancellation_pubsub()
+
+        async def cancellation_subscriber_provider(id: str) -> CancellationSubscriber:
+            return cancellation_pubsub.create_subscriber(id)
+
+        # Set the singleton if file_storage is provided
+        if file_storage is not None:
+            set_file_storage(file_storage)
+
+        return ApiBuilder(
+            repository=repository,
+            authorizer=authorizer,
+            cancellation_subscriber_provider=cancellation_subscriber_provider,
+            cancellation_publisher=cancellation_pubsub.get_publisher(),
+            agent=agent,
+            response_generator=response_generator,
+            file_storage=file_storage,
+        )
+
+    @classmethod
+    def local(
+        cls,
+        agent: Optional[BaseAgent] = None,
+        response_generator: Optional[ResponseGenerator] = None,
+        in_memory: bool = False,
+        file_storage: Optional[BaseFileStorage] = None,
+    ) -> "ApiBuilder":
+        # Use provided file_storage or create a local one
+        storage = file_storage or LocalFileStorage()
+        # Also set the singleton so LangChainService can access it
+        set_file_storage(storage)
+        return cls.stateful(
+            repository=InMemoryThreadRepository() if in_memory else LocalFileThreadRepository(),
+            authorizer=DummyAuthorizer(),
+            agent=agent,
+            response_generator=response_generator,
+            file_storage=storage,
+        )

spaik_sdk/server/api/routers/audio_router_factory.py

@@ -0,0 +1,201 @@
+from typing import Optional
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import Response, StreamingResponse
+from pydantic import BaseModel
+
+from spaik_sdk.audio import AudioFormat, SpeechToText, STTOptions, TextToSpeech, TTSOptions
+from spaik_sdk.server.authorization.base_authorizer import BaseAuthorizer
+from spaik_sdk.server.authorization.base_user import BaseUser
+from spaik_sdk.utils.init_logger import init_logger
+
+logger = init_logger(__name__)
+
+
+class TTSRequest(BaseModel):
+    """Request body for text-to-speech synthesis."""
+
+    text: str
+    model: Optional[str] = None
+    voice: str = "alloy"
+    speed: float = 1.0
+    format: str = "mp3"
+
+
+class STTResponse(BaseModel):
+    """Response from speech-to-text transcription."""
+
+    text: str
+
+
+class AudioRouterFactory:
+    """Factory for creating audio API routes (TTS/STT)."""
+
+    def __init__(
+        self,
+        authorizer: Optional[BaseAuthorizer[BaseUser]] = None,
+        tts_model: Optional[str] = None,
+        stt_model: Optional[str] = None,
+    ):
+        self.authorizer = authorizer
+        self.tts_model = tts_model
+        self.stt_model = stt_model
+
+    def create_router(self, prefix: str = "/audio") -> APIRouter:
+        router = APIRouter(prefix=prefix, tags=["audio"])
+
+        async def get_current_user(request: Request) -> BaseUser:
+            if self.authorizer is None:
+                return BaseUser("anonymous")
+            user = await self.authorizer.get_user(request)
+            if not user:
+                raise HTTPException(status_code=401, detail="Unauthorized")
+            return user
+
+        @router.post("/speech")
+        async def text_to_speech(
+            request: TTSRequest,
+            user: BaseUser = Depends(get_current_user),
+        ):
+            """
+            Convert text to speech audio.
+
+            Returns audio bytes in the specified format (default: mp3).
+            """
+            try:
+                # Map format string to enum
+                format_map = {
+                    "mp3": AudioFormat.MP3,
+                    "opus": AudioFormat.OPUS,
+                    "aac": AudioFormat.AAC,
+                    "flac": AudioFormat.FLAC,
+                    "wav": AudioFormat.WAV,
+                    "pcm": AudioFormat.PCM,
+                }
+                output_format = format_map.get(request.format.lower(), AudioFormat.MP3)
+
+                options = TTSOptions(
+                    voice=request.voice,
+                    speed=request.speed,
+                    output_format=output_format,
+                )
+
+                tts = TextToSpeech(model=request.model or self.tts_model)
+                audio_bytes = await tts.synthesize(text=request.text, options=options)
+
+                # Determine content type
+                content_type_map = {
+                    AudioFormat.MP3: "audio/mpeg",
+                    AudioFormat.OPUS: "audio/opus",
+                    AudioFormat.AAC: "audio/aac",
+                    AudioFormat.FLAC: "audio/flac",
+                    AudioFormat.WAV: "audio/wav",
+                    AudioFormat.PCM: "audio/pcm",
+                }
+                content_type = content_type_map.get(output_format, "audio/mpeg")
+
+                return Response(
+                    content=audio_bytes,
+                    media_type=content_type,
+                    headers={
+                        "Content-Disposition": f'inline; filename="speech.{request.format}"',
+                    },
+                )
+            except Exception as e:
+                logger.error(f"TTS error: {e}")
+                raise HTTPException(status_code=500, detail=str(e))
+
+        @router.post("/speech/stream")
+        async def text_to_speech_stream(
+            request: TTSRequest,
+            user: BaseUser = Depends(get_current_user),
+        ):
+            """
+            Stream text to speech audio.
+
+            Streams audio chunks as they are generated, allowing playback to start immediately.
+            This is faster for the user as audio begins playing before full generation is complete.
+            """
+            try:
+                # Map format string to enum
+                format_map = {
+                    "mp3": AudioFormat.MP3,
+                    "opus": AudioFormat.OPUS,
+                    "aac": AudioFormat.AAC,
+                    "flac": AudioFormat.FLAC,
+                    "wav": AudioFormat.WAV,
+                    "pcm": AudioFormat.PCM,
+                }
+                output_format = format_map.get(request.format.lower(), AudioFormat.MP3)
+
+                options = TTSOptions(
+                    voice=request.voice,
+                    speed=request.speed,
+                    output_format=output_format,
+                )
+
+                tts = TextToSpeech(model=request.model or self.tts_model)
+
+                # Determine content type
+                content_type_map = {
+                    AudioFormat.MP3: "audio/mpeg",
+                    AudioFormat.OPUS: "audio/opus",
+                    AudioFormat.AAC: "audio/aac",
+                    AudioFormat.FLAC: "audio/flac",
+                    AudioFormat.WAV: "audio/wav",
+                    AudioFormat.PCM: "audio/pcm",
+                }
+                content_type = content_type_map.get(output_format, "audio/mpeg")
+
+                async def generate():
+                    async for chunk in tts.synthesize_stream(text=request.text, options=options):
+                        yield chunk
+
+                return StreamingResponse(
+                    generate(),
+                    media_type=content_type,
+                    headers={
+                        "Content-Disposition": f'inline; filename="speech.{request.format}"',
+                        "Cache-Control": "no-cache",
+                    },
+                )
+            except Exception as e:
+                logger.error(f"TTS stream error: {e}")
+                raise HTTPException(status_code=500, detail=str(e))
+
+        @router.post("/transcribe", response_model=STTResponse)
+        async def speech_to_text(
+            file: UploadFile = File(...),
+            language: Optional[str] = Form(None),
+            prompt: Optional[str] = Form(None),
+            user: BaseUser = Depends(get_current_user),
+        ):
+            """
+            Transcribe audio file to text using OpenAI Whisper.
+
+            Accepts audio files in various formats (webm, mp3, wav, m4a, ogg).
+            """
+            try:
+                audio_bytes = await file.read()
+                filename = file.filename or "audio.webm"
+                
+                logger.info(f"STT request: language={language}, filename={filename}, size={len(audio_bytes)}")
+
+                options = STTOptions(
+                    language=language,
+                    prompt=prompt,
+                )
+
+                stt = SpeechToText(model=self.stt_model)
+                text = await stt.transcribe(
+                    audio_bytes=audio_bytes,
+                    options=options,
+                    filename=filename,
+                )
+
+                return STTResponse(text=text)
+            except Exception as e:
+                logger.error(f"STT error: {e}")
+                raise HTTPException(status_code=500, detail=str(e))
+
+        return router