ragnarbot-ai 0.1.0__py3-none-any.whl

ragnarbot/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

ragnarbot/providers/litellm_provider.py

@@ -0,0 +1,135 @@
+"""LiteLLM provider implementation for multi-provider support."""
+
+import os
+from typing import Any
+
+import litellm
+from litellm import acompletion
+
+from ragnarbot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+
+
+class LiteLLMProvider(LLMProvider):
+    """
+    LLM provider using LiteLLM for multi-provider support.
+
+    Supports Anthropic, OpenAI, and Gemini 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"
+    ):
+        super().__init__(api_key, api_base)
+        self.default_model = default_model
+
+        # Configure LiteLLM based on provider
+        if api_key:
+            if "anthropic" in default_model:
+                os.environ.setdefault("ANTHROPIC_API_KEY", api_key)
+            elif "openai" in default_model or "gpt" in default_model:
+                os.environ.setdefault("OPENAI_API_KEY", api_key)
+            elif "gemini" in default_model.lower():
+                os.environ.setdefault("GEMINI_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 Gemini, ensure gemini/ prefix if not already present
+        if "gemini" in model.lower() and not model.startswith("gemini/"):
+            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"
+        
+        try:
+            response = await acompletion(**kwargs)
+            return self._parse_response(response)
+        except Exception as e:
+            # Return error as content for graceful handling
+            return LLMResponse(
+                content=f"Error calling LLM: {str(e)}",
+                finish_reason="error",
+            )
+    
+    def _parse_response(self, response: Any) -> LLMResponse:
+        """Parse LiteLLM response into our standard format."""
+        choice = response.choices[0]
+        message = choice.message
+        
+        tool_calls = []
+        if hasattr(message, "tool_calls") and message.tool_calls:
+            for tc in message.tool_calls:
+                # 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,
+                    name=tc.function.name,
+                    arguments=args,
+                ))
+        
+        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

ragnarbot/providers/transcription.py

@@ -0,0 +1,67 @@
+"""Standalone voice transcription tool using Groq Whisper."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+from loguru import logger
+
+
+class GroqTranscriptionProvider:
+    """
+    Standalone voice transcription tool using Groq's Whisper API.
+
+    This is not an LLM provider — it provides speech-to-text transcription
+    for voice messages. 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 ""

ragnarbot/session/__init__.py

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

ragnarbot/session/manager.py

@@ -0,0 +1,202 @@
+"""Session management for conversation history."""
+
+import json
+from pathlib import Path
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from loguru import logger
+
+from ragnarbot.utils.helpers import ensure_dir, safe_filename
+
+
+@dataclass
+class Session:
+    """
+    A conversation session.
+    
+    Stores messages in JSONL format for easy reading and persistence.
+    """
+    
+    key: str  # channel:chat_id
+    messages: list[dict[str, Any]] = field(default_factory=list)
+    created_at: datetime = field(default_factory=datetime.now)
+    updated_at: datetime = field(default_factory=datetime.now)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    def add_message(self, role: str, content: str, **kwargs: Any) -> None:
+        """Add a message to the session."""
+        msg = {
+            "role": role,
+            "content": content,
+            "timestamp": datetime.now().isoformat(),
+            **kwargs
+        }
+        self.messages.append(msg)
+        self.updated_at = datetime.now()
+    
+    def get_history(self, max_messages: int = 50) -> list[dict[str, Any]]:
+        """
+        Get message history for LLM context.
+        
+        Args:
+            max_messages: Maximum messages to return.
+        
+        Returns:
+            List of messages in LLM format.
+        """
+        # Get recent messages
+        recent = self.messages[-max_messages:] if len(self.messages) > max_messages else self.messages
+        
+        # Convert to LLM format (just role and content)
+        return [{"role": m["role"], "content": m["content"]} for m in recent]
+    
+    def clear(self) -> None:
+        """Clear all messages in the session."""
+        self.messages = []
+        self.updated_at = datetime.now()
+
+
+class SessionManager:
+    """
+    Manages conversation sessions.
+    
+    Sessions are stored as JSONL files in the sessions directory.
+    """
+    
+    def __init__(self, workspace: Path):
+        self.workspace = workspace
+        self.sessions_dir = ensure_dir(Path.home() / ".ragnarbot" / "sessions")
+        self._cache: dict[str, Session] = {}
+    
+    def _get_session_path(self, key: str) -> Path:
+        """Get the file path for a session."""
+        safe_key = safe_filename(key.replace(":", "_"))
+        return self.sessions_dir / f"{safe_key}.jsonl"
+    
+    def get_or_create(self, key: str) -> Session:
+        """
+        Get an existing session or create a new one.
+        
+        Args:
+            key: Session key (usually channel:chat_id).
+        
+        Returns:
+            The session.
+        """
+        # Check cache
+        if key in self._cache:
+            return self._cache[key]
+        
+        # Try to load from disk
+        session = self._load(key)
+        if session is None:
+            session = Session(key=key)
+        
+        self._cache[key] = session
+        return session
+    
+    def _load(self, key: str) -> Session | None:
+        """Load a session from disk."""
+        path = self._get_session_path(key)
+        
+        if not path.exists():
+            return None
+        
+        try:
+            messages = []
+            metadata = {}
+            created_at = None
+            
+            with open(path) as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    
+                    data = json.loads(line)
+                    
+                    if data.get("_type") == "metadata":
+                        metadata = data.get("metadata", {})
+                        created_at = datetime.fromisoformat(data["created_at"]) if data.get("created_at") else None
+                    else:
+                        messages.append(data)
+            
+            return Session(
+                key=key,
+                messages=messages,
+                created_at=created_at or datetime.now(),
+                metadata=metadata
+            )
+        except Exception as e:
+            logger.warning(f"Failed to load session {key}: {e}")
+            return None
+    
+    def save(self, session: Session) -> None:
+        """Save a session to disk."""
+        path = self._get_session_path(session.key)
+        
+        with open(path, "w") as f:
+            # Write metadata first
+            metadata_line = {
+                "_type": "metadata",
+                "created_at": session.created_at.isoformat(),
+                "updated_at": session.updated_at.isoformat(),
+                "metadata": session.metadata
+            }
+            f.write(json.dumps(metadata_line) + "\n")
+            
+            # Write messages
+            for msg in session.messages:
+                f.write(json.dumps(msg) + "\n")
+        
+        self._cache[session.key] = session
+    
+    def delete(self, key: str) -> bool:
+        """
+        Delete a session.
+        
+        Args:
+            key: Session key.
+        
+        Returns:
+            True if deleted, False if not found.
+        """
+        # Remove from cache
+        self._cache.pop(key, None)
+        
+        # Remove file
+        path = self._get_session_path(key)
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+    
+    def list_sessions(self) -> list[dict[str, Any]]:
+        """
+        List all sessions.
+        
+        Returns:
+            List of session info dicts.
+        """
+        sessions = []
+        
+        for path in self.sessions_dir.glob("*.jsonl"):
+            try:
+                # Read just the metadata line
+                with open(path) as f:
+                    first_line = f.readline().strip()
+                    if first_line:
+                        data = json.loads(first_line)
+                        if data.get("_type") == "metadata":
+                            sessions.append({
+                                "key": path.stem.replace("_", ":"),
+                                "created_at": data.get("created_at"),
+                                "updated_at": data.get("updated_at"),
+                                "path": str(path)
+                            })
+            except Exception:
+                continue
+        
+        return sorted(sessions, key=lambda x: x.get("updated_at", ""), reverse=True)

ragnarbot/skills/README.md

@@ -0,0 +1,24 @@
+# ragnarbot Skills
+
+This directory contains built-in skills that extend ragnarbot's capabilities.
+
+## Skill Format
+
+Each skill is a directory containing a `SKILL.md` file with:
+- YAML frontmatter (name, description, metadata)
+- Markdown instructions for the agent
+
+## Attribution
+
+These skills are adapted from [OpenClaw](https://github.com/openclaw/openclaw)'s skill system.
+The skill format and metadata structure follow OpenClaw's conventions to maintain compatibility.
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `github` | Interact with GitHub using the `gh` CLI |
+| `weather` | Get weather info using wttr.in and Open-Meteo |
+| `summarize` | Summarize URLs, files, and YouTube videos |
+| `tmux` | Remote-control tmux sessions |
+| `skill-creator` | Create new skills |

ragnarbot/skills/cron/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: cron
+description: Schedule reminders and recurring tasks.
+---
+
+# Cron
+
+Use the `cron` tool to schedule reminders or recurring tasks.
+
+## Two Modes
+
+1. **Reminder** - message is sent directly to user
+2. **Task** - message is a task description, agent executes and sends result
+
+## Examples
+
+Fixed reminder:
+```
+cron(action="add", message="Time to take a break!", every_seconds=1200)
+```
+
+Dynamic task (agent executes each time):
+```
+cron(action="add", message="Check HKUDS/ragnarbot GitHub stars and report", every_seconds=600)
+```
+
+List/remove:
+```
+cron(action="list")
+cron(action="remove", job_id="abc123")
+```
+
+## Time Expressions
+
+| User says | Parameters |
+|-----------|------------|
+| every 20 minutes | every_seconds: 1200 |
+| every hour | every_seconds: 3600 |
+| every day at 8am | cron_expr: "0 8 * * *" |
+| weekdays at 5pm | cron_expr: "0 17 * * 1-5" |

ragnarbot/skills/github/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: github
+description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
+metadata: {"ragnarbot":{"emoji":"🐙","requires":{"bins":["gh"]},"install":[{"id":"brew","kind":"brew","formula":"gh","bins":["gh"],"label":"Install GitHub CLI (brew)"},{"id":"apt","kind":"apt","package":"gh","bins":["gh"],"label":"Install GitHub CLI (apt)"}]}}
+---
+
+# GitHub Skill
+
+Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.
+
+## Pull Requests
+
+Check CI status on a PR:
+```bash
+gh pr checks 55 --repo owner/repo
+```
+
+List recent workflow runs:
+```bash
+gh run list --repo owner/repo --limit 10
+```
+
+View a run and see which steps failed:
+```bash
+gh run view <run-id> --repo owner/repo
+```
+
+View logs for failed steps only:
+```bash
+gh run view <run-id> --repo owner/repo --log-failed
+```
+
+## API for Advanced Queries
+
+The `gh api` command is useful for accessing data not available through other subcommands.
+
+Get PR with specific fields:
+```bash
+gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
+```
+
+## JSON Output
+
+Most commands support `--json` for structured output.  You can use `--jq` to filter:
+
+```bash
+gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
+```