ragnarbot-ai 0.1.0__py3-none-any.whl

ragnarbot/config/schema.py

@@ -0,0 +1,114 @@
+"""Configuration schema using Pydantic."""
+
+from pathlib import Path
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings
+
+
+class TelegramConfig(BaseModel):
+    """Telegram channel configuration."""
+    enabled: bool = False
+    token: str = ""  # Bot token from @BotFather
+    allow_from: list[str] = Field(default_factory=list)  # Allowed user IDs or usernames
+    proxy: str | None = None  # HTTP/SOCKS5 proxy URL, e.g. "http://127.0.0.1:7890" or "socks5://127.0.0.1:1080"
+
+
+class ChannelsConfig(BaseModel):
+    """Configuration for chat channels."""
+    telegram: TelegramConfig = Field(default_factory=TelegramConfig)
+
+
+class AgentDefaults(BaseModel):
+    """Default agent configuration."""
+    workspace: str = "~/.ragnarbot/workspace"
+    model: str = "anthropic/claude-opus-4-5"
+    max_tokens: int = 8192
+    temperature: float = 0.7
+    max_tool_iterations: int = 20
+
+
+class AgentsConfig(BaseModel):
+    """Agent configuration."""
+    defaults: AgentDefaults = Field(default_factory=AgentDefaults)
+
+
+class ProviderConfig(BaseModel):
+    """LLM provider configuration."""
+    api_key: str = ""
+    api_base: str | None = None
+
+
+class ProvidersConfig(BaseModel):
+    """Configuration for LLM providers."""
+    anthropic: ProviderConfig = Field(default_factory=ProviderConfig)
+    openai: ProviderConfig = Field(default_factory=ProviderConfig)
+    gemini: ProviderConfig = Field(default_factory=ProviderConfig)
+
+
+class TranscriptionConfig(BaseModel):
+    """Voice transcription configuration (Groq Whisper)."""
+    api_key: str = ""  # Groq API key for Whisper
+
+
+class GatewayConfig(BaseModel):
+    """Gateway/server configuration."""
+    host: str = "0.0.0.0"
+    port: int = 18790
+
+
+class WebSearchConfig(BaseModel):
+    """Web search tool configuration."""
+    api_key: str = ""  # Brave Search API key
+    max_results: int = 5
+
+
+class WebToolsConfig(BaseModel):
+    """Web tools configuration."""
+    search: WebSearchConfig = Field(default_factory=WebSearchConfig)
+
+
+class ExecToolConfig(BaseModel):
+    """Shell exec tool configuration."""
+    timeout: int = 60
+    restrict_to_workspace: bool = False  # If true, block commands accessing paths outside workspace
+
+
+class ToolsConfig(BaseModel):
+    """Tools configuration."""
+    web: WebToolsConfig = Field(default_factory=WebToolsConfig)
+    exec: ExecToolConfig = Field(default_factory=ExecToolConfig)
+
+
+class Config(BaseSettings):
+    """Root configuration for ragnarbot."""
+    agents: AgentsConfig = Field(default_factory=AgentsConfig)
+    channels: ChannelsConfig = Field(default_factory=ChannelsConfig)
+    providers: ProvidersConfig = Field(default_factory=ProvidersConfig)
+    transcription: TranscriptionConfig = Field(default_factory=TranscriptionConfig)
+    gateway: GatewayConfig = Field(default_factory=GatewayConfig)
+    tools: ToolsConfig = Field(default_factory=ToolsConfig)
+    
+    @property
+    def workspace_path(self) -> Path:
+        """Get expanded workspace path."""
+        return Path(self.agents.defaults.workspace).expanduser()
+    
+    def get_api_key(self) -> str | None:
+        """Get API key in priority order: Anthropic > OpenAI > Gemini."""
+        return (
+            self.providers.anthropic.api_key or
+            self.providers.openai.api_key or
+            self.providers.gemini.api_key or
+            None
+        )
+
+    def get_api_base(self) -> str | None:
+        """Get API base URL if a provider has a custom base configured."""
+        for provider in [self.providers.anthropic, self.providers.openai, self.providers.gemini]:
+            if provider.api_base:
+                return provider.api_base
+        return None
+    
+    class Config:
+        env_prefix = "RAGNARBOT_"
+        env_nested_delimiter = "__"

ragnarbot/cron/__init__.py

@@ -0,0 +1,6 @@
+"""Cron service for scheduled agent tasks."""
+
+from ragnarbot.cron.service import CronService
+from ragnarbot.cron.types import CronJob, CronSchedule
+
+__all__ = ["CronService", "CronJob", "CronSchedule"]

ragnarbot/cron/service.py

@@ -0,0 +1,346 @@
+"""Cron service for scheduling agent tasks."""
+
+import asyncio
+import json
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Callable, Coroutine
+
+from loguru import logger
+
+from ragnarbot.cron.types import CronJob, CronJobState, CronPayload, CronSchedule, CronStore
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _compute_next_run(schedule: CronSchedule, now_ms: int) -> int | None:
+    """Compute next run time in ms."""
+    if schedule.kind == "at":
+        return schedule.at_ms if schedule.at_ms and schedule.at_ms > now_ms else None
+    
+    if schedule.kind == "every":
+        if not schedule.every_ms or schedule.every_ms <= 0:
+            return None
+        # Next interval from now
+        return now_ms + schedule.every_ms
+    
+    if schedule.kind == "cron" and schedule.expr:
+        try:
+            from croniter import croniter
+            cron = croniter(schedule.expr, time.time())
+            next_time = cron.get_next()
+            return int(next_time * 1000)
+        except Exception:
+            return None
+    
+    return None
+
+
+class CronService:
+    """Service for managing and executing scheduled jobs."""
+    
+    def __init__(
+        self,
+        store_path: Path,
+        on_job: Callable[[CronJob], Coroutine[Any, Any, str | None]] | None = None
+    ):
+        self.store_path = store_path
+        self.on_job = on_job  # Callback to execute job, returns response text
+        self._store: CronStore | None = None
+        self._timer_task: asyncio.Task | None = None
+        self._running = False
+    
+    def _load_store(self) -> CronStore:
+        """Load jobs from disk."""
+        if self._store:
+            return self._store
+        
+        if self.store_path.exists():
+            try:
+                data = json.loads(self.store_path.read_text())
+                jobs = []
+                for j in data.get("jobs", []):
+                    jobs.append(CronJob(
+                        id=j["id"],
+                        name=j["name"],
+                        enabled=j.get("enabled", True),
+                        schedule=CronSchedule(
+                            kind=j["schedule"]["kind"],
+                            at_ms=j["schedule"].get("atMs"),
+                            every_ms=j["schedule"].get("everyMs"),
+                            expr=j["schedule"].get("expr"),
+                            tz=j["schedule"].get("tz"),
+                        ),
+                        payload=CronPayload(
+                            kind=j["payload"].get("kind", "agent_turn"),
+                            message=j["payload"].get("message", ""),
+                            deliver=j["payload"].get("deliver", False),
+                            channel=j["payload"].get("channel"),
+                            to=j["payload"].get("to"),
+                        ),
+                        state=CronJobState(
+                            next_run_at_ms=j.get("state", {}).get("nextRunAtMs"),
+                            last_run_at_ms=j.get("state", {}).get("lastRunAtMs"),
+                            last_status=j.get("state", {}).get("lastStatus"),
+                            last_error=j.get("state", {}).get("lastError"),
+                        ),
+                        created_at_ms=j.get("createdAtMs", 0),
+                        updated_at_ms=j.get("updatedAtMs", 0),
+                        delete_after_run=j.get("deleteAfterRun", False),
+                    ))
+                self._store = CronStore(jobs=jobs)
+            except Exception as e:
+                logger.warning(f"Failed to load cron store: {e}")
+                self._store = CronStore()
+        else:
+            self._store = CronStore()
+        
+        return self._store
+    
+    def _save_store(self) -> None:
+        """Save jobs to disk."""
+        if not self._store:
+            return
+        
+        self.store_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        data = {
+            "version": self._store.version,
+            "jobs": [
+                {
+                    "id": j.id,
+                    "name": j.name,
+                    "enabled": j.enabled,
+                    "schedule": {
+                        "kind": j.schedule.kind,
+                        "atMs": j.schedule.at_ms,
+                        "everyMs": j.schedule.every_ms,
+                        "expr": j.schedule.expr,
+                        "tz": j.schedule.tz,
+                    },
+                    "payload": {
+                        "kind": j.payload.kind,
+                        "message": j.payload.message,
+                        "deliver": j.payload.deliver,
+                        "channel": j.payload.channel,
+                        "to": j.payload.to,
+                    },
+                    "state": {
+                        "nextRunAtMs": j.state.next_run_at_ms,
+                        "lastRunAtMs": j.state.last_run_at_ms,
+                        "lastStatus": j.state.last_status,
+                        "lastError": j.state.last_error,
+                    },
+                    "createdAtMs": j.created_at_ms,
+                    "updatedAtMs": j.updated_at_ms,
+                    "deleteAfterRun": j.delete_after_run,
+                }
+                for j in self._store.jobs
+            ]
+        }
+        
+        self.store_path.write_text(json.dumps(data, indent=2))
+    
+    async def start(self) -> None:
+        """Start the cron service."""
+        self._running = True
+        self._load_store()
+        self._recompute_next_runs()
+        self._save_store()
+        self._arm_timer()
+        logger.info(f"Cron service started with {len(self._store.jobs if self._store else [])} jobs")
+    
+    def stop(self) -> None:
+        """Stop the cron service."""
+        self._running = False
+        if self._timer_task:
+            self._timer_task.cancel()
+            self._timer_task = None
+    
+    def _recompute_next_runs(self) -> None:
+        """Recompute next run times for all enabled jobs."""
+        if not self._store:
+            return
+        now = _now_ms()
+        for job in self._store.jobs:
+            if job.enabled:
+                job.state.next_run_at_ms = _compute_next_run(job.schedule, now)
+    
+    def _get_next_wake_ms(self) -> int | None:
+        """Get the earliest next run time across all jobs."""
+        if not self._store:
+            return None
+        times = [j.state.next_run_at_ms for j in self._store.jobs 
+                 if j.enabled and j.state.next_run_at_ms]
+        return min(times) if times else None
+    
+    def _arm_timer(self) -> None:
+        """Schedule the next timer tick."""
+        if self._timer_task:
+            self._timer_task.cancel()
+        
+        next_wake = self._get_next_wake_ms()
+        if not next_wake or not self._running:
+            return
+        
+        delay_ms = max(0, next_wake - _now_ms())
+        delay_s = delay_ms / 1000
+        
+        async def tick():
+            await asyncio.sleep(delay_s)
+            if self._running:
+                await self._on_timer()
+        
+        self._timer_task = asyncio.create_task(tick())
+    
+    async def _on_timer(self) -> None:
+        """Handle timer tick - run due jobs."""
+        if not self._store:
+            return
+        
+        now = _now_ms()
+        due_jobs = [
+            j for j in self._store.jobs
+            if j.enabled and j.state.next_run_at_ms and now >= j.state.next_run_at_ms
+        ]
+        
+        for job in due_jobs:
+            await self._execute_job(job)
+        
+        self._save_store()
+        self._arm_timer()
+    
+    async def _execute_job(self, job: CronJob) -> None:
+        """Execute a single job."""
+        start_ms = _now_ms()
+        logger.info(f"Cron: executing job '{job.name}' ({job.id})")
+        
+        try:
+            response = None
+            if self.on_job:
+                response = await self.on_job(job)
+            
+            job.state.last_status = "ok"
+            job.state.last_error = None
+            logger.info(f"Cron: job '{job.name}' completed")
+            
+        except Exception as e:
+            job.state.last_status = "error"
+            job.state.last_error = str(e)
+            logger.error(f"Cron: job '{job.name}' failed: {e}")
+        
+        job.state.last_run_at_ms = start_ms
+        job.updated_at_ms = _now_ms()
+        
+        # Handle one-shot jobs
+        if job.schedule.kind == "at":
+            if job.delete_after_run:
+                self._store.jobs = [j for j in self._store.jobs if j.id != job.id]
+            else:
+                job.enabled = False
+                job.state.next_run_at_ms = None
+        else:
+            # Compute next run
+            job.state.next_run_at_ms = _compute_next_run(job.schedule, _now_ms())
+    
+    # ========== Public API ==========
+    
+    def list_jobs(self, include_disabled: bool = False) -> list[CronJob]:
+        """List all jobs."""
+        store = self._load_store()
+        jobs = store.jobs if include_disabled else [j for j in store.jobs if j.enabled]
+        return sorted(jobs, key=lambda j: j.state.next_run_at_ms or float('inf'))
+    
+    def add_job(
+        self,
+        name: str,
+        schedule: CronSchedule,
+        message: str,
+        deliver: bool = False,
+        channel: str | None = None,
+        to: str | None = None,
+        delete_after_run: bool = False,
+    ) -> CronJob:
+        """Add a new job."""
+        store = self._load_store()
+        now = _now_ms()
+        
+        job = CronJob(
+            id=str(uuid.uuid4())[:8],
+            name=name,
+            enabled=True,
+            schedule=schedule,
+            payload=CronPayload(
+                kind="agent_turn",
+                message=message,
+                deliver=deliver,
+                channel=channel,
+                to=to,
+            ),
+            state=CronJobState(next_run_at_ms=_compute_next_run(schedule, now)),
+            created_at_ms=now,
+            updated_at_ms=now,
+            delete_after_run=delete_after_run,
+        )
+        
+        store.jobs.append(job)
+        self._save_store()
+        self._arm_timer()
+        
+        logger.info(f"Cron: added job '{name}' ({job.id})")
+        return job
+    
+    def remove_job(self, job_id: str) -> bool:
+        """Remove a job by ID."""
+        store = self._load_store()
+        before = len(store.jobs)
+        store.jobs = [j for j in store.jobs if j.id != job_id]
+        removed = len(store.jobs) < before
+        
+        if removed:
+            self._save_store()
+            self._arm_timer()
+            logger.info(f"Cron: removed job {job_id}")
+        
+        return removed
+    
+    def enable_job(self, job_id: str, enabled: bool = True) -> CronJob | None:
+        """Enable or disable a job."""
+        store = self._load_store()
+        for job in store.jobs:
+            if job.id == job_id:
+                job.enabled = enabled
+                job.updated_at_ms = _now_ms()
+                if enabled:
+                    job.state.next_run_at_ms = _compute_next_run(job.schedule, _now_ms())
+                else:
+                    job.state.next_run_at_ms = None
+                self._save_store()
+                self._arm_timer()
+                return job
+        return None
+    
+    async def run_job(self, job_id: str, force: bool = False) -> bool:
+        """Manually run a job."""
+        store = self._load_store()
+        for job in store.jobs:
+            if job.id == job_id:
+                if not force and not job.enabled:
+                    return False
+                await self._execute_job(job)
+                self._save_store()
+                self._arm_timer()
+                return True
+        return False
+    
+    def status(self) -> dict:
+        """Get service status."""
+        store = self._load_store()
+        return {
+            "enabled": self._running,
+            "jobs": len(store.jobs),
+            "next_wake_at_ms": self._get_next_wake_ms(),
+        }

ragnarbot/cron/types.py

@@ -0,0 +1,59 @@
+"""Cron types."""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class CronSchedule:
+    """Schedule definition for a cron job."""
+    kind: Literal["at", "every", "cron"]
+    # For "at": timestamp in ms
+    at_ms: int | None = None
+    # For "every": interval in ms
+    every_ms: int | None = None
+    # For "cron": cron expression (e.g. "0 9 * * *")
+    expr: str | None = None
+    # Timezone for cron expressions
+    tz: str | None = None
+
+
+@dataclass
+class CronPayload:
+    """What to do when the job runs."""
+    kind: Literal["system_event", "agent_turn"] = "agent_turn"
+    message: str = ""
+    # Deliver response to channel
+    deliver: bool = False
+    channel: str | None = None  # e.g. "telegram"
+    to: str | None = None  # e.g. phone number
+
+
+@dataclass
+class CronJobState:
+    """Runtime state of a job."""
+    next_run_at_ms: int | None = None
+    last_run_at_ms: int | None = None
+    last_status: Literal["ok", "error", "skipped"] | None = None
+    last_error: str | None = None
+
+
+@dataclass
+class CronJob:
+    """A scheduled job."""
+    id: str
+    name: str
+    enabled: bool = True
+    schedule: CronSchedule = field(default_factory=lambda: CronSchedule(kind="every"))
+    payload: CronPayload = field(default_factory=CronPayload)
+    state: CronJobState = field(default_factory=CronJobState)
+    created_at_ms: int = 0
+    updated_at_ms: int = 0
+    delete_after_run: bool = False
+
+
+@dataclass
+class CronStore:
+    """Persistent store for cron jobs."""
+    version: int = 1
+    jobs: list[CronJob] = field(default_factory=list)

ragnarbot/heartbeat/__init__.py

@@ -0,0 +1,5 @@
+"""Heartbeat service for periodic agent wake-ups."""
+
+from ragnarbot.heartbeat.service import HeartbeatService
+
+__all__ = ["HeartbeatService"]

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

ragnarbot/providers/__init__.py

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