kyber-chat 1.0.0__py3-none-any.whl

kyber/heartbeat/service.py

@@ -0,0 +1,130 @@
+"""Heartbeat service - periodic agent wake-up to check for tasks."""
+
+import asyncio
+from pathlib import Path
+from typing import Any, Callable, Coroutine
+
+from loguru import logger
+
+# Default interval: 30 minutes
+DEFAULT_HEARTBEAT_INTERVAL_S = 30 * 60
+
+# The prompt sent to agent during heartbeat
+HEARTBEAT_PROMPT = """Read HEARTBEAT.md in your workspace (if it exists).
+Follow any instructions or tasks listed there.
+If nothing needs attention, reply with just: HEARTBEAT_OK"""
+
+# Token that indicates "nothing to do"
+HEARTBEAT_OK_TOKEN = "HEARTBEAT_OK"
+
+
+def _is_heartbeat_empty(content: str | None) -> bool:
+    """Check if HEARTBEAT.md has no actionable content."""
+    if not content:
+        return True
+    
+    # Lines to skip: empty, headers, HTML comments, empty checkboxes
+    skip_patterns = {"- [ ]", "* [ ]", "- [x]", "* [x]"}
+    
+    for line in content.split("\n"):
+        line = line.strip()
+        if not line or line.startswith("#") or line.startswith("<!--") or line in skip_patterns:
+            continue
+        return False  # Found actionable content
+    
+    return True
+
+
+class HeartbeatService:
+    """
+    Periodic heartbeat service that wakes the agent to check for tasks.
+    
+    The agent reads HEARTBEAT.md from the workspace and executes any
+    tasks listed there. If nothing needs attention, it replies HEARTBEAT_OK.
+    """
+    
+    def __init__(
+        self,
+        workspace: Path,
+        on_heartbeat: Callable[[str], Coroutine[Any, Any, str]] | None = None,
+        interval_s: int = DEFAULT_HEARTBEAT_INTERVAL_S,
+        enabled: bool = True,
+    ):
+        self.workspace = workspace
+        self.on_heartbeat = on_heartbeat
+        self.interval_s = interval_s
+        self.enabled = enabled
+        self._running = False
+        self._task: asyncio.Task | None = None
+    
+    @property
+    def heartbeat_file(self) -> Path:
+        return self.workspace / "HEARTBEAT.md"
+    
+    def _read_heartbeat_file(self) -> str | None:
+        """Read HEARTBEAT.md content."""
+        if self.heartbeat_file.exists():
+            try:
+                return self.heartbeat_file.read_text()
+            except Exception:
+                return None
+        return None
+    
+    async def start(self) -> None:
+        """Start the heartbeat service."""
+        if not self.enabled:
+            logger.info("Heartbeat disabled")
+            return
+        
+        self._running = True
+        self._task = asyncio.create_task(self._run_loop())
+        logger.info(f"Heartbeat started (every {self.interval_s}s)")
+    
+    def stop(self) -> None:
+        """Stop the heartbeat service."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            self._task = None
+    
+    async def _run_loop(self) -> None:
+        """Main heartbeat loop."""
+        while self._running:
+            try:
+                await asyncio.sleep(self.interval_s)
+                if self._running:
+                    await self._tick()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Heartbeat error: {e}")
+    
+    async def _tick(self) -> None:
+        """Execute a single heartbeat tick."""
+        content = self._read_heartbeat_file()
+        
+        # Skip if HEARTBEAT.md is empty or doesn't exist
+        if _is_heartbeat_empty(content):
+            logger.debug("Heartbeat: no tasks (HEARTBEAT.md empty)")
+            return
+        
+        logger.info("Heartbeat: checking for tasks...")
+        
+        if self.on_heartbeat:
+            try:
+                response = await self.on_heartbeat(HEARTBEAT_PROMPT)
+                
+                # Check if agent said "nothing to do"
+                if HEARTBEAT_OK_TOKEN.replace("_", "") in response.upper().replace("_", ""):
+                    logger.info("Heartbeat: OK (no action needed)")
+                else:
+                    logger.info(f"Heartbeat: completed task")
+                    
+            except Exception as e:
+                logger.error(f"Heartbeat execution failed: {e}")
+    
+    async def trigger_now(self) -> str | None:
+        """Manually trigger a heartbeat."""
+        if self.on_heartbeat:
+            return await self.on_heartbeat(HEARTBEAT_PROMPT)
+        return None

kyber/providers/__init__.py

@@ -0,0 +1,6 @@
+"""LLM provider abstraction module."""
+
+from kyber.providers.base import LLMProvider, LLMResponse
+from kyber.providers.litellm_provider import LiteLLMProvider
+
+__all__ = ["LLMProvider", "LLMResponse", "LiteLLMProvider"]

kyber/providers/base.py

@@ -0,0 +1,69 @@
+"""Base LLM provider interface."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolCallRequest:
+    """A tool call request from the LLM."""
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass
+class LLMResponse:
+    """Response from an LLM provider."""
+    content: str | None
+    tool_calls: list[ToolCallRequest] = field(default_factory=list)
+    finish_reason: str = "stop"
+    usage: dict[str, int] = field(default_factory=dict)
+    
+    @property
+    def has_tool_calls(self) -> bool:
+        """Check if response contains tool calls."""
+        return len(self.tool_calls) > 0
+
+
+class LLMProvider(ABC):
+    """
+    Abstract base class for LLM providers.
+    
+    Implementations should handle the specifics of each provider's API
+    while maintaining a consistent interface.
+    """
+    
+    def __init__(self, api_key: str | None = None, api_base: str | None = None):
+        self.api_key = api_key
+        self.api_base = api_base
+    
+    @abstractmethod
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        model: str | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+    ) -> LLMResponse:
+        """
+        Send a chat completion request.
+        
+        Args:
+            messages: List of message dicts with 'role' and 'content'.
+            tools: Optional list of tool definitions.
+            model: Model identifier (provider-specific).
+            max_tokens: Maximum tokens in response.
+            temperature: Sampling temperature.
+        
+        Returns:
+            LLMResponse with content and/or tool calls.
+        """
+        pass
+    
+    @abstractmethod
+    def get_default_model(self) -> str:
+        """Get the default model for this provider."""
+        pass

kyber/providers/litellm_provider.py

@@ -0,0 +1,227 @@
+"""LiteLLM provider implementation for multi-provider support."""
+
+import os
+from typing import Any
+
+import litellm
+from litellm import acompletion
+from loguru import logger
+
+from kyber.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+
+
+class LiteLLMProvider(LLMProvider):
+    """
+    LLM provider using LiteLLM for multi-provider support.
+    
+    Supports OpenRouter, Anthropic, OpenAI, Gemini, and many other providers through
+    a unified interface.
+    """
+    
+    def __init__(
+        self, 
+        api_key: str | None = None, 
+        api_base: str | None = None,
+        default_model: str = "anthropic/claude-opus-4-5",
+        provider_name: str | None = None,
+    ):
+        super().__init__(api_key, api_base)
+        self.default_model = default_model
+        self.provider_name = provider_name.strip().lower() if provider_name else None
+        
+        if self.provider_name:
+            self.is_openrouter = self.provider_name == "openrouter"
+            self.is_vllm = self.provider_name == "vllm"
+        else:
+            # Detect OpenRouter by api_key prefix or explicit api_base
+            self.is_openrouter = (
+                (api_key and api_key.startswith("sk-or-")) or
+                (api_base and "openrouter" in api_base)
+            )
+            # Track if using custom endpoint (vLLM, etc.)
+            self.is_vllm = bool(api_base) and not self.is_openrouter
+        
+        # Configure LiteLLM based on provider
+        if api_key:
+            if self.is_openrouter:
+                # OpenRouter mode - set key
+                os.environ["OPENROUTER_API_KEY"] = api_key
+            elif self.is_vllm:
+                # vLLM/custom endpoint - uses OpenAI-compatible API
+                os.environ.setdefault("OPENAI_API_KEY", api_key)
+            elif self.provider_name == "deepseek" or "deepseek" in default_model:
+                os.environ.setdefault("DEEPSEEK_API_KEY", api_key)
+            elif self.provider_name == "anthropic" or "anthropic" in default_model:
+                os.environ.setdefault("ANTHROPIC_API_KEY", api_key)
+            elif self.provider_name == "openai" or "openai" in default_model or "gpt" in default_model:
+                os.environ.setdefault("OPENAI_API_KEY", api_key)
+            elif self.provider_name == "gemini" or "gemini" in default_model.lower():
+                os.environ.setdefault("GEMINI_API_KEY", api_key)
+            elif self.provider_name == "zhipu" or "glm" in default_model or "zhipu" in default_model or "zai" in default_model:
+                os.environ.setdefault("ZHIPUAI_API_KEY", api_key)
+            elif self.provider_name == "groq" or "groq" in default_model:
+                os.environ.setdefault("GROQ_API_KEY", api_key)
+        
+        if api_base:
+            litellm.api_base = api_base
+        
+        # Disable LiteLLM logging noise
+        litellm.suppress_debug_info = True
+    
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        model: str | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+    ) -> LLMResponse:
+        """
+        Send a chat completion request via LiteLLM.
+        
+        Args:
+            messages: List of message dicts with 'role' and 'content'.
+            tools: Optional list of tool definitions in OpenAI format.
+            model: Model identifier (e.g., 'anthropic/claude-sonnet-4-5').
+            max_tokens: Maximum tokens in response.
+            temperature: Sampling temperature.
+        
+        Returns:
+            LLMResponse with content and/or tool calls.
+        """
+        model = model or self.default_model
+        
+        # For OpenRouter, prefix model name if not already prefixed
+        if self.is_openrouter and not model.startswith("openrouter/"):
+            model = f"openrouter/{model}"
+        
+        # For Zhipu/Z.ai, ensure prefix is present
+        # Handle cases like "glm-4.7-flash" -> "zai/glm-4.7-flash"
+        if ("glm" in model.lower() or "zhipu" in model.lower()) and not (
+            model.startswith("zhipu/") or 
+            model.startswith("zai/") or 
+            model.startswith("openrouter/")
+        ):
+            model = f"zai/{model}"
+
+        # For vLLM, use hosted_vllm/ prefix per LiteLLM docs
+        if self.is_vllm:
+            model = f"hosted_vllm/{model}"
+        
+        # For Gemini, ensure gemini/ prefix if not already present.
+        # Skip if routing via OpenRouter (openrouter/...) since that provider handles it.
+        if (
+            "gemini" in model.lower()
+            and not model.startswith("gemini/")
+            and not model.startswith("openrouter/")
+        ):
+            model = f"gemini/{model}"
+        
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+        }
+        
+        # Pass api_base directly for custom endpoints (vLLM, etc.)
+        if self.api_base:
+            kwargs["api_base"] = self.api_base
+        
+        if tools:
+            kwargs["tools"] = tools
+            kwargs["tool_choice"] = "auto"
+        
+        last_error: Exception | None = None
+        for attempt in range(3):
+            try:
+                response = await acompletion(**kwargs)
+                return self._parse_response(response)
+            except Exception as e:
+                last_error = e
+                error_str = str(e)
+                # Retry on transient / parse errors from the provider
+                is_transient = any(tok in error_str.lower() for tok in [
+                    "unable to get json response",
+                    "expecting value",
+                    "jsondecodeerror",
+                    "timeout",
+                    "rate limit",
+                    "429",
+                    "500",
+                    "502",
+                    "503",
+                    "504",
+                    "overloaded",
+                    "connection",
+                ])
+                if is_transient and attempt < 2:
+                    wait = 2 ** attempt  # 1s, 2s
+                    logger.warning(
+                        f"LLM call failed (attempt {attempt + 1}/3), "
+                        f"retrying in {wait}s: {error_str}"
+                    )
+                    import asyncio
+                    await asyncio.sleep(wait)
+                    continue
+                # Non-transient or final attempt — return error as content
+                return LLMResponse(
+                    content=f"Error calling LLM: {error_str}",
+                    finish_reason="error",
+                )
+        # Should not reach here, but just in case
+        return LLMResponse(
+            content=f"Error calling LLM: {str(last_error)}",
+            finish_reason="error",
+        )
+    
+    def _parse_response(self, response: Any) -> LLMResponse:
+        """Parse LiteLLM response into our standard format."""
+        try:
+            choice = response.choices[0]
+        except (IndexError, AttributeError):
+            logger.warning("LLM response has no choices")
+            return LLMResponse(content=None, finish_reason="error")
+
+        message = choice.message
+        
+        tool_calls = []
+        if hasattr(message, "tool_calls") and message.tool_calls:
+            for tc in message.tool_calls:
+                try:
+                    # Parse arguments from JSON string if needed
+                    args = tc.function.arguments
+                    if isinstance(args, str):
+                        import json
+                        try:
+                            args = json.loads(args)
+                        except json.JSONDecodeError:
+                            args = {"raw": args}
+                    
+                    tool_calls.append(ToolCallRequest(
+                        id=tc.id or f"call_{id(tc)}",
+                        name=tc.function.name,
+                        arguments=args,
+                    ))
+                except (AttributeError, TypeError) as e:
+                    logger.warning(f"Skipping malformed tool call: {e}")
+                    continue
+        
+        usage = {}
+        if hasattr(response, "usage") and response.usage:
+            usage = {
+                "prompt_tokens": response.usage.prompt_tokens,
+                "completion_tokens": response.usage.completion_tokens,
+                "total_tokens": response.usage.total_tokens,
+            }
+        
+        return LLMResponse(
+            content=message.content,
+            tool_calls=tool_calls,
+            finish_reason=choice.finish_reason or "stop",
+            usage=usage,
+        )
+    
+    def get_default_model(self) -> str:
+        """Get the default model."""
+        return self.default_model

kyber/providers/transcription.py

@@ -0,0 +1,65 @@
+"""Voice transcription provider using Groq."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+from loguru import logger
+
+
+class GroqTranscriptionProvider:
+    """
+    Voice transcription provider using Groq's Whisper API.
+    
+    Groq offers extremely fast transcription with a generous free tier.
+    """
+    
+    def __init__(self, api_key: str | None = None):
+        self.api_key = api_key or os.environ.get("GROQ_API_KEY")
+        self.api_url = "https://api.groq.com/openai/v1/audio/transcriptions"
+    
+    async def transcribe(self, file_path: str | Path) -> str:
+        """
+        Transcribe an audio file using Groq.
+        
+        Args:
+            file_path: Path to the audio file.
+            
+        Returns:
+            Transcribed text.
+        """
+        if not self.api_key:
+            logger.warning("Groq API key not configured for transcription")
+            return ""
+        
+        path = Path(file_path)
+        if not path.exists():
+            logger.error(f"Audio file not found: {file_path}")
+            return ""
+        
+        try:
+            async with httpx.AsyncClient() as client:
+                with open(path, "rb") as f:
+                    files = {
+                        "file": (path.name, f),
+                        "model": (None, "whisper-large-v3"),
+                    }
+                    headers = {
+                        "Authorization": f"Bearer {self.api_key}",
+                    }
+                    
+                    response = await client.post(
+                        self.api_url,
+                        headers=headers,
+                        files=files,
+                        timeout=60.0
+                    )
+                    
+                    response.raise_for_status()
+                    data = response.json()
+                    return data.get("text", "")
+                    
+        except Exception as e:
+            logger.error(f"Groq transcription error: {e}")
+            return ""

kyber/session/__init__.py

@@ -0,0 +1,5 @@
+"""Session management module."""
+
+from kyber.session.manager import SessionManager, Session
+
+__all__ = ["SessionManager", "Session"]