zrt 0.0.1b1__py3-none-any.whl

zrt/__init__.py

@@ -0,0 +1,41 @@
+"""Zero Runtime (ZRT) — Python SDK.
+
+Thin runtime SDK: you author agents and the ZRT cloud runtime executes the
+real-time pipeline (media, VAD, turn detection, STT, LLM, TTS) over gRPC. The
+agent-facing API lives in ``zrt.agents`` with providers under ``zrt.plugins``.
+
+This top-level module stays dependency-free (no gRPC stubs) so importing
+``zrt`` is cheap.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+__version__ = "0.0.1b1"
+
+
+@dataclass
+class PubSubPublishConfig:
+    """Config for publishing a message on a room pubsub topic.
+
+    Fields:
+      * ``topic`` — pubsub topic name (e.g. ``"CHAT"``, ``"AGENT_EVENT"``).
+      * ``message`` — payload body (string or JSON-serializable value).
+      * ``mode`` — ``"sendOnly"`` (default) or ``"sendAndPersist"``.
+      * ``send_only`` — legacy alias; ``True`` forces ``mode='sendOnly'``.
+      * ``payload`` — optional structured payload alongside ``message``.
+    """
+
+    topic: str
+    message: Any = ""
+    mode: str = "sendOnly"
+    send_only: bool = False
+    payload: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self) -> None:
+        if self.send_only:
+            self.mode = "sendOnly"
+
+
+__all__ = ["PubSubPublishConfig", "__version__"]

zrt/agents/__init__.py

@@ -0,0 +1,312 @@
+import logging
+import os
+import sys
+from typing import Any, Optional
+
+def setup_logging(level=logging.INFO):
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s', datefmt='%Y-%m-%d %H:%M:%S')
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(formatter)
+    logger = logging.getLogger('zrt.agents')
+    logger.setLevel(level)
+    for handler in logger.handlers[:]:
+        logger.removeHandler(handler)
+    logger.addHandler(console_handler)
+    logger.propagate = False
+    return logger
+from .agent import Agent
+from .session import AgentSession
+from .pipeline import Pipeline, PipelineHooks, PipelineHookError
+from .utterance import UtteranceHandle
+from .enums import UserState, AgentState, PipelineMode, RealtimeMode, PipelineComponent, PipelineConfig, SpeechEventType, VADEventType, ChatRole, ToolChoice, RecordingFormat, RecordingChannelMode, RecordingTranscriptFormat, RecordingState
+from .config import EOUConfig, InterruptConfig, RealtimeConfig, ContextWindow, RecordingConfig, S3StorageConfig, RecordingTranscriptConfig
+from .tools import function_tool, is_function_tool, get_tool_info, FunctionTool, FunctionToolInfo, build_openai_schema, build_gemini_schema, build_nova_sonic_schema
+from .providers import STT, STTResponse, SpeechData, LLM, LLMResponse, TTS, VAD, VADResponse, VADData, EOU
+from .chat import ChatContext, ChatMessage, ChatContent, FunctionCall, FunctionCallOutput, ImageContent
+from .event_emitter import EventEmitter
+from .job import WorkerJob, JobContext, RoomOptions, RecordingOptions, Options, WebSocketConfig, WebRTCConfig, TracesOptions, MetricsOptions, LoggingOptions
+
+class _StubMeta(type):
+
+    def __getattr__(cls, name):
+        return _Stub()
+
+class _Stub(metaclass=_StubMeta):
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def __call__(self, *args, **kwargs):
+        return self
+
+    def __getattr__(self, name):
+        return _Stub()
+
+class RealtimeBaseModel:
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        return None
+
+    async def cleanup(self) -> None:
+        await self.aclose()
+
+def RealtimeLLMAdapter(realtime_model, agent=None):
+    try:
+        setattr(realtime_model, '_is_realtime_model', True)
+    except (AttributeError, TypeError):
+        pass
+    return realtime_model
+ExecutorType = _Stub
+ResourceType = _Stub
+TaskType = _Stub
+ResourceConfig = _Stub
+TaskConfig = _Stub
+TaskResult = _Stub
+TaskStatus = _Stub
+ResourceStatus = _Stub
+ResourceInfo = _Stub
+HealthMetrics = _Stub
+ResourceManager = _Stub
+ProcessResource = _Stub
+ThreadResource = _Stub
+TaskExecutor = _Stub
+DedicatedInferenceResource = _Stub
+CustomAudioStreamTrack = _Stub
+TeeCustomAudioStreamTrack = _Stub
+TeeMixingCustomAudioStreamTrack = _Stub
+from .mcp import MCPServerStdio, MCPServerHTTP
+from .a2a import AgentCard, A2AMessage
+from .knowledge_base import KnowledgeBaseConfig, KnowledgeBase
+from .images import EncodeOptions, ResizeOptions, encode, coerce_image_to_jpeg_bytes, DEFAULT_REALTIME_ENCODE_OPTIONS
+from .dtmf_handler import DTMFHandler
+from .voice_mail_detector import VoiceMailDetector
+from .fallback import FallbackSTT, FallbackLLM, FallbackTTS
+from .denoise import Denoise
+ConversationalGraphResponse = _Stub
+GraphPipelineAdapter = _Stub
+from .background_audio import BackgroundAudioHandlerConfig
+from .handoff import agent_switch, AGENT_SWITCH_KEY
+
+class _EventBus:
+
+    def on(self, *args, **kwargs):
+        pass
+
+    def emit(self, *args, **kwargs):
+        pass
+global_event_emitter = _EventBus()
+
+class EventTypes:
+    pass
+
+class _MetricsCollector:
+
+    def __init__(self) -> None:
+        self.turns: list[dict] = []
+
+    def __getattr__(self, name):
+        return lambda *a, **kw: None
+metrics_collector = _MetricsCollector()
+
+class WorkerType:
+    ROOM = 'room'
+    PUBLISHER = 'publisher'
+from dataclasses import dataclass as _ds_worker, field as _f_worker
+
+@_ds_worker
+class WorkerPermissions:
+    can_publish: bool = True
+    can_subscribe: bool = True
+    can_publish_data: bool = True
+    can_update_metadata: bool = True
+    hidden: bool = False
+    agent: bool = True
+
+@_ds_worker
+class WorkerOptions:
+    entrypoint_fnc: Any = None
+    request_fnc: Any = None
+    initialize_process_fnc: Any = None
+    executor_type: Any = None
+    num_idle_processes: int = 2
+    initialize_timeout: float = 10.0
+    close_timeout: float = 60.0
+    memory_warn_mb: float = 500.0
+    memory_limit_mb: float = 0.0
+    ping_interval: float = 30.0
+    max_processes: int = 10
+    agent_id: str = 'ZeroRuntimeAgent'
+    auth_token: Optional[str] = None
+    worker_type: str = WorkerType.ROOM
+    permissions: WorkerPermissions = _f_worker(default_factory=WorkerPermissions)
+    max_retry: int = 16
+    load_threshold: float = 0.75
+    register: bool = False
+    signaling_base_url: str = os.environ.get('ZRT_SIGNALING_URL', 'api.videosdk.live')
+    host: str = '0.0.0.0'
+    port: int = 8081
+    log_level: str = 'INFO'
+
+class Worker:
+
+    def __init__(self, options: Optional[WorkerOptions]=None, default_room_options=None):
+        self.options = options
+        self.default_room_options = default_room_options
+
+    @staticmethod
+    def run_worker(options: Optional[WorkerOptions]=None, default_room_options=None):
+        if options is None or options.entrypoint_fnc is None:
+            raise ValueError('Worker.run_worker requires WorkerOptions(entrypoint_fnc=...). For the new API prefer WorkerJob(entrypoint=...).start().')
+        new_opts = Options(executor_type=options.executor_type, num_idle_processes=options.num_idle_processes, initialize_timeout=options.initialize_timeout, close_timeout=options.close_timeout, memory_warn_mb=options.memory_warn_mb, memory_limit_mb=options.memory_limit_mb, ping_interval=options.ping_interval, max_processes=options.max_processes, agent_id=options.agent_id, auth_token=options.auth_token, permissions=options.permissions, max_retry=options.max_retry, load_threshold=options.load_threshold, register=options.register, signaling_base_url=options.signaling_base_url, host=options.host, port=options.port, log_level=options.log_level)
+        jobctx = None
+        if default_room_options is not None:
+            jobctx = lambda: JobContext(room_options=default_room_options)
+        job = WorkerJob(entrypoint=options.entrypoint_fnc, jobctx=jobctx, options=new_opts)
+        job.start()
+
+class FlushMarker:
+
+    def __repr__(self) -> str:
+        return '<FlushMarker>'
+from .job import ObservabilityOptions
+
+class TTSAudioCache:
+
+    def __init__(self, *args, **kwargs) -> None:
+        self._files: dict[str, bytes] = {}
+
+    def add(self, key: str, data: bytes) -> None:
+        self._files[key] = data
+
+    def get(self, key: str) -> Optional[bytes]:
+        return self._files.get(key)
+
+    def clear(self) -> None:
+        self._files.clear()
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._files
+
+def load_audio_file(path: str) -> bytes:
+    try:
+        with open(path, 'rb') as f:
+            return f.read()
+    except (FileNotFoundError, IsADirectoryError, PermissionError):
+        return b''
+
+class SentenceChunker:
+
+    def __init__(self, *args, **kwargs) -> None:
+        pass
+
+    def chunk(self, text: str) -> list[str]:
+        return [text] if text else []
+
+    def __call__(self, text: str) -> list[str]:
+        return self.chunk(text)
+
+class SentenceChunkStream:
+
+    def __init__(self, *args, **kwargs) -> None:
+        pass
+
+    async def __aiter__(self):
+        if False:
+            yield ''
+
+class BufferedSentenceChunkStream(SentenceChunkStream):
+    pass
+
+class BasicSentenceChunker(SentenceChunker):
+    pass
+
+class IndicSentenceChunker(SentenceChunker):
+    pass
+
+class IndicScriptTransliterator:
+
+    def __init__(self, *args, **kwargs) -> None:
+        pass
+
+    def transliterate(self, text: str, target_script: str='deva') -> str:
+        return text
+
+class TextFilter:
+
+    def __init__(self, *args, **kwargs) -> None:
+        pass
+
+    def filter(self, text: str) -> str:
+        return text
+
+    def __call__(self, text: str) -> str:
+        return self.filter(text)
+
+class BasicTextFilter(TextFilter):
+    pass
+
+class EnglishHyphenator:
+
+    def __init__(self, *args, **kwargs) -> None:
+        pass
+
+    def hyphenate(self, word: str) -> str:
+        return word
+
+def hyphenate_english(word: str) -> str:
+    return word
+
+def detect_script(text: str) -> str:
+    return 'latin'
+
+def normalize_lang_code(code: Optional[str]) -> str:
+    return (code or 'en').split('-')[0].lower()
+
+def pre_warm_tokenizer(*args, **kwargs) -> None:
+    return None
+INDIC_LANGS: list[str] = ['hi', 'bn', 'gu', 'kn', 'ml', 'mr', 'or', 'pa', 'ta', 'te', 'ur', 'as', 'sa', 'sd']
+import asyncio as _asyncio_for_run_helpers
+import contextvars as _contextvars
+_STT_OBSERVATION_QUEUE: _contextvars.ContextVar = _contextvars.ContextVar('_zrt_stt_observation_queue', default=None)
+
+async def run_stt(audio_stream):
+    queue = _STT_OBSERVATION_QUEUE.get()
+    if queue is None:
+        async for _ in audio_stream:
+            pass
+        return
+
+    async def _drain():
+        try:
+            async for _ in audio_stream:
+                pass
+        except Exception:
+            pass
+    drain_task = _asyncio_for_run_helpers.create_task(_drain())
+    try:
+        while True:
+            event = await queue.get()
+            if event is None:
+                return
+            yield event
+    finally:
+        drain_task.cancel()
+        try:
+            await drain_task
+        except BaseException:
+            pass
+
+async def run_tts(text_stream):
+    async for _ in text_stream:
+        pass
+
+async def segment_text(chunks, **kwargs):
+    async for chunk in chunks:
+        yield chunk
+__all__ = ['Agent', 'AgentSession', 'Pipeline', 'PipelineHooks', 'PipelineHookError', 'UtteranceHandle', 'UserState', 'AgentState', 'PipelineMode', 'RealtimeMode', 'PipelineComponent', 'PipelineConfig', 'SpeechEventType', 'VADEventType', 'ChatRole', 'ToolChoice', 'EOUConfig', 'InterruptConfig', 'RealtimeConfig', 'ContextWindow', 'RecordingConfig', 'S3StorageConfig', 'RecordingTranscriptConfig', 'RecordingFormat', 'RecordingChannelMode', 'RecordingTranscriptFormat', 'RecordingState', 'function_tool', 'is_function_tool', 'get_tool_info', 'FunctionTool', 'FunctionToolInfo', 'build_openai_schema', 'build_gemini_schema', 'build_nova_sonic_schema', 'STT', 'STTResponse', 'SpeechData', 'LLM', 'LLMResponse', 'TTS', 'FlushMarker', 'VAD', 'VADResponse', 'VADData', 'EOU', 'ChatContext', 'ChatMessage', 'ChatContent', 'FunctionCall', 'FunctionCallOutput', 'ImageContent', 'EventEmitter', 'global_event_emitter', 'EventTypes', 'WorkerJob', 'JobContext', 'RoomOptions', 'RecordingOptions', 'Options', 'WebSocketConfig', 'WebRTCConfig', 'TracesOptions', 'MetricsOptions', 'LoggingOptions', 'ObservabilityOptions', 'Worker', 'WorkerOptions', 'WorkerType', 'WorkerPermissions', 'RealtimeBaseModel', 'RealtimeLLMAdapter', 'CustomAudioStreamTrack', 'TeeCustomAudioStreamTrack', 'TeeMixingCustomAudioStreamTrack', 'MCPServerStdio', 'MCPServerHTTP', 'AgentCard', 'A2AMessage', 'EncodeOptions', 'ResizeOptions', 'encode', 'coerce_image_to_jpeg_bytes', 'DEFAULT_REALTIME_ENCODE_OPTIONS', 'KnowledgeBaseConfig', 'KnowledgeBase', 'DTMFHandler', 'VoiceMailDetector', 'FallbackSTT', 'FallbackLLM', 'FallbackTTS', 'ConversationalGraphResponse', 'GraphPipelineAdapter', 'BackgroundAudioHandlerConfig', 'agent_switch', 'AGENT_SWITCH_KEY', 'ExecutorType', 'ResourceType', 'TaskType', 'ResourceConfig', 'TaskConfig', 'TaskResult', 'TaskStatus', 'ResourceStatus', 'ResourceInfo', 'HealthMetrics', 'ResourceManager', 'ProcessResource', 'ThreadResource', 'TaskExecutor', 'DedicatedInferenceResource', 'metrics_collector', 'setup_logging', 'run_stt', 'run_tts', 'segment_text', 'SentenceChunker', 'SentenceChunkStream', 'BufferedSentenceChunkStream', 'BasicSentenceChunker', 'IndicSentenceChunker', 'IndicScriptTransliterator', 'TextFilter', 'BasicTextFilter', 'EnglishHyphenator', 'hyphenate_english', 'detect_script', 'normalize_lang_code', 'INDIC_LANGS', 'pre_warm_tokenizer', 'TTSAudioCache', 'load_audio_file']