ragnarbot-ai 0.1.0__tar.gz

ragnarbot_ai-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.assets
+.env
+*.pyc
+dist/
+build/
+docs/
+*.egg-info/
+*.egg
+*.pyc
+*.pyo
+*.pyd
+*.pyw
+*.pyz
+*.pywz
+*.pyzz
+.venv/
+__pycache__/

ragnarbot_ai-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 nanobot contributors
+Copyright (c) 2025 BlckLvls
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ragnarbot_ai-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: ragnarbot-ai
+Version: 0.1.0
+Summary: A lightweight personal AI assistant framework
+Author: BlckLvls
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,chatbot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: croniter>=2.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: litellm>=1.0.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-telegram-bot>=21.0
+Requires-Dist: readability-lxml>=0.8.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'

ragnarbot_ai-0.1.0/README.md

@@ -0,0 +1,183 @@
+<div align="center">
+  <img src="ragnarbot_logo.jpg" alt="ragnarbot" width="500">
+</div>
+
+<p align="center">
+  <em>Async-first personal AI assistant. Lightweight, extensible, runs anywhere.</em>
+</p>
+
+---
+
+## Install
+
+Install [uv](https://github.com/astral-sh/uv) if you don't have it:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then install ragnarbot:
+
+```bash
+uv tool install ragnarbot-ai
+```
+
+## Quick Start
+
+**1. Initialize**
+
+```bash
+ragnarbot onboard
+```
+
+**2. Configure**
+
+Add your API key to `~/.ragnarbot/config.json`:
+
+```json
+{
+  "providers": {
+    "anthropic": {
+      "apiKey": "sk-ant-xxx"
+    }
+  }
+}
+```
+
+Get an API key from [Anthropic](https://console.anthropic.com/keys), [OpenAI](https://platform.openai.com/api-keys), or [Google AI Studio](https://aistudio.google.com/apikey).
+
+**3. Chat**
+
+```bash
+ragnarbot agent -m "What can you do?"
+```
+
+Or start an interactive session:
+
+```bash
+ragnarbot agent
+```
+
+## Telegram
+
+ragnarbot is designed to work through Telegram. Set up a bot, point it at your instance, and you have a personal AI assistant in your pocket.
+
+**Create a bot**
+
+Open Telegram, find `@BotFather`, send `/newbot`, and follow the prompts. Copy the token.
+
+**Get your user ID**
+
+Message `@userinfobot` on Telegram to get your numeric user ID.
+
+**Add to config**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allowFrom": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**Run the gateway**
+
+```bash
+ragnarbot gateway
+```
+
+Your bot is live. Message it from Telegram.
+
+## Configuration
+
+All configuration lives in `~/.ragnarbot/config.json`. Keys are camelCase.
+
+### Providers
+
+Only one provider is required. ragnarbot uses [LiteLLM](https://github.com/BerriAI/litellm) under the hood, so any model string LiteLLM supports will work.
+
+| Provider | Config key | Models | API Key |
+|----------|-----------|--------|---------|
+| Anthropic | `providers.anthropic` | `anthropic/claude-*` | [console.anthropic.com](https://console.anthropic.com) |
+| OpenAI | `providers.openai` | `openai/gpt-*` | [platform.openai.com](https://platform.openai.com) |
+| Gemini | `providers.gemini` | `gemini/*` | [aistudio.google.com](https://aistudio.google.com) |
+
+Set the default model under `agents.defaults.model`.
+
+### Transcription
+
+Voice messages in Telegram are automatically transcribed when a Groq API key is configured. Groq provides free access to Whisper.
+
+```json
+{
+  "transcription": {
+    "apiKey": "gsk_xxx"
+  }
+}
+```
+
+Get a key at [console.groq.com](https://console.groq.com).
+
+### Web Search
+
+ragnarbot can search the web via the Brave Search API.
+
+```json
+{
+  "tools": {
+    "web": {
+      "search": {
+        "apiKey": "BSA-xxx"
+      }
+    }
+  }
+}
+```
+
+Get a key at [brave.com/search/api](https://brave.com/search/api/).
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `ragnarbot onboard` | Initialize config and workspace |
+| `ragnarbot agent -m "..."` | Send a single message |
+| `ragnarbot agent` | Interactive chat session |
+| `ragnarbot gateway` | Start gateway (Telegram + cron + heartbeat) |
+| `ragnarbot status` | Show configuration status |
+| `ragnarbot channels status` | Show channel status |
+| `ragnarbot cron list` | List scheduled jobs |
+| `ragnarbot cron add` | Add a scheduled job |
+| `ragnarbot cron remove <id>` | Remove a scheduled job |
+
+## Architecture
+
+ragnarbot is async-first and built around a simple message-passing architecture:
+
+```
+Telegram --> MessageBus --> AgentLoop --> LLM --> Tools
+                                  \                /
+                                   \-- Sessions --/
+```
+
+**MessageBus** decouples channels from agent logic using async queues. Channels publish inbound messages; the agent publishes responses back.
+
+**AgentLoop** consumes messages, builds context (system prompt, conversation history, skills), calls the LLM, and executes tool calls in a loop. It also exposes a `process_direct()` path for CLI usage and cron jobs.
+
+**Tools** are registered in a `ToolRegistry` and exposed to the LLM as OpenAI-compatible function calls. Built-in tools include file operations, shell execution, web search, cron management, and sub-agent spawning.
+
+**Skills** are markdown files with YAML frontmatter. Skills marked `always: true` are included in every prompt; others appear as summaries the agent can load on demand.
+
+**Sessions** persist conversation history as JSONL files under `~/.ragnarbot/sessions/`.
+
+## License
+
+MIT
+
+---
+
+<sub>Based on [nanobot](https://github.com/HKUDS/nanobot)</sub>

ragnarbot_ai-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "ragnarbot-ai"
+version = "0.1.0"
+description = "A lightweight personal AI assistant framework"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "BlckLvls"}
+]
+keywords = ["ai", "agent", "chatbot"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "typer>=0.9.0",
+    "litellm>=1.0.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "httpx>=0.25.0",
+    "loguru>=0.7.0",
+    "readability-lxml>=0.8.0",
+    "rich>=13.0.0",
+    "croniter>=2.0.0",
+    "python-telegram-bot>=21.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+ragnarbot = "ragnarbot.cli.commands:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ragnarbot"]
+
+[tool.hatch.build.targets.wheel.sources]
+"ragnarbot" = "ragnarbot"
+
+# Include non-Python files in skills
+[tool.hatch.build]
+include = [
+    "ragnarbot/**/*.py",
+    "ragnarbot/skills/**/*.md",
+    "ragnarbot/skills/**/*.sh",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "ragnarbot/",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

ragnarbot_ai-0.1.0/ragnarbot/__init__.py

@@ -0,0 +1,6 @@
+"""
+ragnarbot - A lightweight AI agent framework
+"""
+
+__version__ = "0.1.0"
+__logo__ = "🤖"

ragnarbot_ai-0.1.0/ragnarbot/__main__.py

@@ -0,0 +1,8 @@
+"""
+Entry point for running ragnarbot as a module: python -m ragnarbot
+"""
+
+from ragnarbot.cli.commands import app
+
+if __name__ == "__main__":
+    app()

ragnarbot_ai-0.1.0/ragnarbot/agent/__init__.py

@@ -0,0 +1,8 @@
+"""Agent core module."""
+
+from ragnarbot.agent.loop import AgentLoop
+from ragnarbot.agent.context import ContextBuilder
+from ragnarbot.agent.memory import MemoryStore
+from ragnarbot.agent.skills import SkillsLoader
+
+__all__ = ["AgentLoop", "ContextBuilder", "MemoryStore", "SkillsLoader"]

ragnarbot_ai-0.1.0/ragnarbot/agent/context.py

@@ -0,0 +1,223 @@
+"""Context builder for assembling agent prompts."""
+
+import base64
+import mimetypes
+from pathlib import Path
+from typing import Any
+
+from ragnarbot.agent.memory import MemoryStore
+from ragnarbot.agent.skills import SkillsLoader
+
+
+class ContextBuilder:
+    """
+    Builds the context (system prompt + messages) for the agent.
+    
+    Assembles bootstrap files, memory, skills, and conversation history
+    into a coherent prompt for the LLM.
+    """
+    
+    BOOTSTRAP_FILES = ["AGENTS.md", "SOUL.md", "USER.md", "TOOLS.md", "IDENTITY.md"]
+    
+    def __init__(self, workspace: Path):
+        self.workspace = workspace
+        self.memory = MemoryStore(workspace)
+        self.skills = SkillsLoader(workspace)
+    
+    def build_system_prompt(self, skill_names: list[str] | None = None) -> str:
+        """
+        Build the system prompt from bootstrap files, memory, and skills.
+        
+        Args:
+            skill_names: Optional list of skills to include.
+        
+        Returns:
+            Complete system prompt.
+        """
+        parts = []
+        
+        # Core identity
+        parts.append(self._get_identity())
+        
+        # Bootstrap files
+        bootstrap = self._load_bootstrap_files()
+        if bootstrap:
+            parts.append(bootstrap)
+        
+        # Memory context
+        memory = self.memory.get_memory_context()
+        if memory:
+            parts.append(f"# Memory\n\n{memory}")
+        
+        # Skills - progressive loading
+        # 1. Always-loaded skills: include full content
+        always_skills = self.skills.get_always_skills()
+        if always_skills:
+            always_content = self.skills.load_skills_for_context(always_skills)
+            if always_content:
+                parts.append(f"# Active Skills\n\n{always_content}")
+        
+        # 2. Available skills: only show summary (agent uses read_file to load)
+        skills_summary = self.skills.build_skills_summary()
+        if skills_summary:
+            parts.append(f"""# Skills
+
+The following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool.
+Skills with available="false" need dependencies installed first - you can try installing them with apt/brew.
+
+{skills_summary}""")
+        
+        return "\n\n---\n\n".join(parts)
+    
+    def _get_identity(self) -> str:
+        """Get the core identity section."""
+        from datetime import datetime
+        now = datetime.now().strftime("%Y-%m-%d %H:%M (%A)")
+        workspace_path = str(self.workspace.expanduser().resolve())
+        
+        return f"""# ragnarbot 🤖
+
+You are ragnarbot, a helpful AI assistant. You have access to tools that allow you to:
+- Read, write, and edit files
+- Execute shell commands
+- Search the web and fetch web pages
+- Send messages to users on chat channels
+- Spawn subagents for complex background tasks
+
+## Current Time
+{now}
+
+## Workspace
+Your workspace is at: {workspace_path}
+- Memory files: {workspace_path}/memory/MEMORY.md
+- Daily notes: {workspace_path}/memory/YYYY-MM-DD.md
+- Custom skills: {workspace_path}/skills/{{skill-name}}/SKILL.md
+
+IMPORTANT: When responding to direct questions or conversations, reply directly with your text response.
+Only use the 'message' tool when you need to send a message to a specific chat channel.
+For normal conversation, just respond with text - do not call the message tool.
+
+Always be helpful, accurate, and concise. When using tools, explain what you're doing.
+When remembering something, write to {workspace_path}/memory/MEMORY.md"""
+    
+    def _load_bootstrap_files(self) -> str:
+        """Load all bootstrap files from workspace."""
+        parts = []
+        
+        for filename in self.BOOTSTRAP_FILES:
+            file_path = self.workspace / filename
+            if file_path.exists():
+                content = file_path.read_text(encoding="utf-8")
+                parts.append(f"## {filename}\n\n{content}")
+        
+        return "\n\n".join(parts) if parts else ""
+    
+    def build_messages(
+        self,
+        history: list[dict[str, Any]],
+        current_message: str,
+        skill_names: list[str] | None = None,
+        media: list[str] | None = None,
+        channel: str | None = None,
+        chat_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Build the complete message list for an LLM call.
+
+        Args:
+            history: Previous conversation messages.
+            current_message: The new user message.
+            skill_names: Optional skills to include.
+            media: Optional list of local file paths for images/media.
+            channel: Current channel (e.g. telegram).
+            chat_id: Current chat/user ID.
+
+        Returns:
+            List of messages including system prompt.
+        """
+        messages = []
+
+        # System prompt
+        system_prompt = self.build_system_prompt(skill_names)
+        if channel and chat_id:
+            system_prompt += f"\n\n## Current Session\nChannel: {channel}\nChat ID: {chat_id}"
+        messages.append({"role": "system", "content": system_prompt})
+
+        # History
+        messages.extend(history)
+
+        # Current message (with optional image attachments)
+        user_content = self._build_user_content(current_message, media)
+        messages.append({"role": "user", "content": user_content})
+
+        return messages
+
+    def _build_user_content(self, text: str, media: list[str] | None) -> str | list[dict[str, Any]]:
+        """Build user message content with optional base64-encoded images."""
+        if not media:
+            return text
+        
+        images = []
+        for path in media:
+            p = Path(path)
+            mime, _ = mimetypes.guess_type(path)
+            if not p.is_file() or not mime or not mime.startswith("image/"):
+                continue
+            b64 = base64.b64encode(p.read_bytes()).decode()
+            images.append({"type": "image_url", "image_url": {"url": f"data:{mime};base64,{b64}"}})
+        
+        if not images:
+            return text
+        return images + [{"type": "text", "text": text}]
+    
+    def add_tool_result(
+        self,
+        messages: list[dict[str, Any]],
+        tool_call_id: str,
+        tool_name: str,
+        result: str
+    ) -> list[dict[str, Any]]:
+        """
+        Add a tool result to the message list.
+        
+        Args:
+            messages: Current message list.
+            tool_call_id: ID of the tool call.
+            tool_name: Name of the tool.
+            result: Tool execution result.
+        
+        Returns:
+            Updated message list.
+        """
+        messages.append({
+            "role": "tool",
+            "tool_call_id": tool_call_id,
+            "name": tool_name,
+            "content": result
+        })
+        return messages
+    
+    def add_assistant_message(
+        self,
+        messages: list[dict[str, Any]],
+        content: str | None,
+        tool_calls: list[dict[str, Any]] | None = None
+    ) -> list[dict[str, Any]]:
+        """
+        Add an assistant message to the message list.
+        
+        Args:
+            messages: Current message list.
+            content: Message content.
+            tool_calls: Optional tool calls.
+        
+        Returns:
+            Updated message list.
+        """
+        msg: dict[str, Any] = {"role": "assistant", "content": content or ""}
+        
+        if tool_calls:
+            msg["tool_calls"] = tool_calls
+        
+        messages.append(msg)
+        return messages