soleclaw 0.1.0__tar.gz

soleclaw-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: soleclaw
+Version: 0.1.0
+Summary: Self-evolving personal AI assistant
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: claude-agent-sdk>=0.1
+Requires-Dist: typer>=0.12
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: loguru>=0.7
+Requires-Dist: rich>=13.0
+Requires-Dist: python-telegram-bot<22.0,>=21.0
+Provides-Extra: telegram
+Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
+Provides-Extra: viking
+Requires-Dist: openviking>=0.1; extra == "viking"
+Provides-Extra: forge
+Requires-Dist: aiosqlite>=0.20; extra == "forge"
+Provides-Extra: cron
+Requires-Dist: croniter>=2.0; extra == "cron"
+Provides-Extra: all
+Requires-Dist: soleclaw[cron,forge,telegram,viking]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"

soleclaw-0.1.0/README.md

@@ -0,0 +1,86 @@
+# Soleclaw
+
+A self-evolving personal AI assistant. Instead of shipping fixed tools, soleclaw **forges its own** — the agent identifies what it needs, generates the code, and integrates it into its toolkit permanently.
+
+Inspired by [nanobot](https://github.com/HKUDS/nanobot) and [openclaw](https://github.com/anthropics/openclaw). Built on [claude-agent-sdk](https://github.com/anthropics/claude-agent-sdk).
+
+## Why
+
+Most agent frameworks extend capabilities through markdown skills that teach the agent how to chain built-in tools. Every invocation requires LLM reasoning through the same chain. Skills are knowledge, not capability.
+
+Soleclaw's forge generates **real executable code** registered as first-class tools. The LLM's role shifts from multi-step orchestrator to single-step dispatcher — pick the right tool, pass the right arguments, done. All logic lives in the generated tool's code, not in the LLM's reasoning chain.
+
+The tool library is model-agnostic. Swap Claude for another model and every tool, every piece of data continues to work.
+
+## Architecture
+
+```
+User (Telegram / CLI)
+  → Channel Layer
+    → SoleclawBridge
+      ├── ContextBuilder → system prompt (identity, memory, skills, tools)
+      ├── @tool functions → in-process MCP server
+      └── ClaudeSDKClient → LLM calls + tool execution loop
+    → Bus (OutboundMessage)
+  → Channel → User
+```
+
+```
+soleclaw/
+├── core/           Bridge, context builder, bootstrap
+├── tools/          MCP tool definitions + user tool library
+├── forge/          Tool generation engine
+├── memory/         Local backend + OpenViking (optional)
+├── cron/           Scheduled tasks (cron/every/at)
+├── skills/         SKILL.md loader
+├── channels/       Telegram, CLI
+├── bus/            Async message routing
+├── config/         Pydantic config schema
+└── cli/            CLI commands (typer)
+```
+
+~2900 lines of core code, 39 source files.
+
+## Setup
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone <repo-url> && cd soleclaw
+uv sync --all-extras
+
+# Configure (interactive wizard)
+soleclaw configure
+```
+
+## Usage
+
+```bash
+# Run as gateway with telegram, configure can also run gateway automatically
+soleclaw gateway start
+
+# Interactive CLI chat
+soleclaw agent
+soleclaw agent "hello"
+```
+
+## Forge — Tool Generation
+
+When the agent identifies a missing capability, it invokes the forge:
+
+1. Agent proposes a tool to the user
+2. User confirms
+3. `forge_tool` spawns a ClaudeSDKClient sub-session to generate code
+4. Generated tool lands in `~/.soleclaw/tool-library/<name>/`
+5. Tool is immediately available via `run_user_tool`
+
+Tool library structure:
+```
+tool-library/
+  └── <tool-name>/
+      ├── manifest.json    # name, description, parameters
+      └── tool.py          # async def execute(args: dict) -> dict
+```
+
+All tool data is stored in a shared SQLite database (`~/.soleclaw/data/store.db`), so tools can cross-reference each other's data.
+

soleclaw-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "soleclaw"
+version = "0.1.0"
+description = "Self-evolving personal AI assistant"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "httpx>=0.27",
+    "claude-agent-sdk>=0.1",
+    "typer>=0.12",
+    "prompt-toolkit>=3.0",
+    "loguru>=0.7",
+    "rich>=13.0",
+    "python-telegram-bot>=21.0,<22.0",
+]
+
+[project.optional-dependencies]
+telegram = ["python-telegram-bot>=21.0"]
+viking = ["openviking>=0.1"]
+forge = ["aiosqlite>=0.20"]
+cron = ["croniter>=2.0"]
+all = ["soleclaw[telegram,viking,forge,cron]"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24"]
+
+[project.scripts]
+soleclaw = "soleclaw.cli.commands:app"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

soleclaw-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

soleclaw-0.1.0/src/soleclaw/bus/events.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class InboundMessage:
+    channel: str
+    sender_id: str
+    chat_id: str
+    content: str
+    thread_id: str = ""
+    timestamp: datetime = field(default_factory=datetime.now)
+    media: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def session_key(self) -> str:
+        return f"{self.channel}:{self.chat_id}"
+
+
+@dataclass
+class OutboundMessage:
+    channel: str
+    chat_id: str
+    content: str
+    thread_id: str = ""
+    reply_to: str | None = None
+    media: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)

soleclaw-0.1.0/src/soleclaw/bus/queue.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+import asyncio
+from .events import InboundMessage, OutboundMessage
+
+
+class MessageBus:
+    def __init__(self) -> None:
+        self.inbound: asyncio.Queue[InboundMessage] = asyncio.Queue()
+        self.outbound: asyncio.Queue[OutboundMessage] = asyncio.Queue()
+
+    async def publish_inbound(self, msg: InboundMessage) -> None:
+        await self.inbound.put(msg)
+
+    async def consume_inbound(self) -> InboundMessage:
+        return await self.inbound.get()
+
+    async def publish_outbound(self, msg: OutboundMessage) -> None:
+        await self.outbound.put(msg)
+
+    async def consume_outbound(self) -> OutboundMessage:
+        return await self.outbound.get()

soleclaw-0.1.0/src/soleclaw/channels/base.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..bus.events import InboundMessage, OutboundMessage
+from ..bus.queue import MessageBus
+
+
+class BaseChannel(ABC):
+    name: str = "base"
+
+    def __init__(self, config: Any, bus: MessageBus):
+        self.config = config
+        self.bus = bus
+
+    @abstractmethod
+    async def start(self) -> None: ...
+
+    @abstractmethod
+    async def stop(self) -> None: ...
+
+    @abstractmethod
+    async def send(self, msg: OutboundMessage) -> None: ...
+
+    async def send_typing(self, chat_id: str, thread_id: str = "") -> None:
+        pass
+
+    async def _handle_message(self, sender_id: str, chat_id: str, content: str) -> None:
+        msg = InboundMessage(channel=self.name, sender_id=sender_id, chat_id=chat_id, content=content)
+        await self.bus.publish_inbound(msg)

soleclaw-0.1.0/src/soleclaw/channels/cli.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from ..bus.events import OutboundMessage
+from ..bus.queue import MessageBus
+from .base import BaseChannel
+
+
+class CLIChannel(BaseChannel):
+    name = "cli"
+
+    def __init__(self, bus: MessageBus):
+        super().__init__(config=None, bus=bus)
+
+    async def start(self) -> None:
+        pass
+
+    async def stop(self) -> None:
+        pass
+
+    async def send(self, msg: OutboundMessage) -> None:
+        print(f"\n{msg.content}\n")

soleclaw-0.1.0/src/soleclaw/channels/manager.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from .base import BaseChannel
+from ..bus.queue import MessageBus
+
+log = logging.getLogger(__name__)
+
+
+class ChannelManager:
+    def __init__(self, bus: MessageBus) -> None:
+        self.bus = bus
+        self._channels: dict[str, BaseChannel] = {}
+        self._running = False
+
+    def add(self, channel: BaseChannel) -> None:
+        self._channels[channel.name] = channel
+
+    async def start_all(self) -> None:
+        for name, ch in self._channels.items():
+            try:
+                await ch.start()
+                log.info("Channel %s started", name)
+            except Exception:
+                log.exception("Failed to start channel %s", name)
+
+    async def stop_all(self) -> None:
+        self._running = False
+        for name, ch in self._channels.items():
+            try:
+                await ch.stop()
+                log.info("Channel %s stopped", name)
+            except Exception:
+                log.exception("Failed to stop channel %s", name)
+
+    async def send_typing(self, channel: str, chat_id: str, thread_id: str = "") -> None:
+        ch = self._channels.get(channel)
+        if ch:
+            await ch.send_typing(chat_id, thread_id)
+
+    async def _dispatch_loop(self) -> None:
+        while self._running:
+            try:
+                msg = await asyncio.wait_for(self.bus.consume_outbound(), timeout=1.0)
+            except asyncio.TimeoutError:
+                continue
+            ch = self._channels.get(msg.channel)
+            if not ch:
+                log.warning("No channel %r for outbound message to %s", msg.channel, msg.chat_id)
+                continue
+            try:
+                await ch.send(msg)
+            except Exception:
+                log.exception("Failed to send outbound on channel %s", msg.channel)
+
+    async def run(self) -> None:
+        self._running = True
+        await self.start_all()
+        log.info("ChannelManager running with %d channel(s)", len(self._channels))
+        try:
+            await self._dispatch_loop()
+        finally:
+            await self.stop_all()

soleclaw-0.1.0/src/soleclaw/channels/telegram.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+import logging
+import re
+
+from telegram import Update
+from telegram.ext import Application, MessageHandler, filters, ContextTypes
+
+from .base import BaseChannel
+from ..bus.queue import MessageBus
+from ..bus.events import InboundMessage, OutboundMessage
+
+logger = logging.getLogger(__name__)
+
+MAX_MESSAGE_LENGTH = 4096
+
+
+def _markdown_to_html(text: str) -> str:
+    if not text:
+        return ""
+
+    code_blocks: list[str] = []
+    def _save_block(m: re.Match) -> str:
+        code_blocks.append(m.group(1))
+        return f"\x00CB{len(code_blocks) - 1}\x00"
+    text = re.sub(r'```[\w]*\n?([\s\S]*?)```', _save_block, text)
+
+    inline_codes: list[str] = []
+    def _save_inline(m: re.Match) -> str:
+        inline_codes.append(m.group(1))
+        return f"\x00IC{len(inline_codes) - 1}\x00"
+    text = re.sub(r'`([^`]+)`', _save_inline, text)
+
+    text = re.sub(r'^#{1,6}\s+(.+)$', r'<b>\1</b>', text, flags=re.MULTILINE)
+    text = re.sub(r'^>\s*(.*)$', r'\1', text, flags=re.MULTILINE)
+
+    text = text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+    text = re.sub(r'\[([^\]]+)\]\(([^)]+)\)', r'<a href="\2">\1</a>', text)
+    text = re.sub(r'\*\*(.+?)\*\*', r'<b>\1</b>', text)
+    text = re.sub(r'__(.+?)__', r'<b>\1</b>', text)
+    text = re.sub(r'(?<![a-zA-Z0-9])_([^_]+)_(?![a-zA-Z0-9])', r'<i>\1</i>', text)
+    text = re.sub(r'~~(.+?)~~', r'<s>\1</s>', text)
+    text = re.sub(r'^[-*]\s+', '• ', text, flags=re.MULTILINE)
+
+    def _esc(s: str) -> str:
+        return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+    for i, code in enumerate(inline_codes):
+        text = text.replace(f"\x00IC{i}\x00", f"<code>{_esc(code)}</code>")
+    for i, code in enumerate(code_blocks):
+        text = text.replace(f"\x00CB{i}\x00", f"<pre><code>{_esc(code)}</code></pre>")
+
+    return text
+
+
+class TelegramChannel(BaseChannel):
+    name = "telegram"
+
+    def __init__(self, bus: MessageBus, token: str, allowed_users: list[str]):
+        super().__init__(config=None, bus=bus)
+        self._token = token
+        self._allowed_users = set(allowed_users) if allowed_users else set()
+        self._app: Application | None = None
+
+    def _is_allowed(self, username: str) -> bool:
+        if not self._allowed_users:
+            return True
+        return username in self._allowed_users
+
+    async def _handle_tg_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        user = update.effective_user
+        if not user or not self._is_allowed(user.username or ""):
+            logger.debug("Ignored message from %s", user)
+            return
+
+        if not update.message or not update.message.text:
+            return
+
+        text = update.message.text
+        reply = update.message.reply_to_message
+        if reply and reply.text:
+            sender_name = reply.from_user.first_name if reply.from_user else "Unknown"
+            text = f"[Replying to {sender_name}: {reply.text}]\n\n{text}"
+
+        chat_id = str(update.effective_chat.id)
+        thread_id = str(update.message.message_thread_id) if update.message.message_thread_id else ""
+        sender = user.username or ""
+        logger.debug("Telegram inbound: chat=%s thread=%s user=%s text=%s", chat_id, thread_id, sender, text[:100])
+
+        msg = InboundMessage(channel=self.name, sender_id=sender, chat_id=chat_id, content=text, thread_id=thread_id)
+        await self.bus.publish_inbound(msg)
+
+    async def send_typing(self, chat_id: str, thread_id: str = "") -> None:
+        if not self._app:
+            return
+        try:
+            kwargs: dict = {"chat_id": int(chat_id), "action": "typing"}
+            if thread_id:
+                kwargs["message_thread_id"] = int(thread_id)
+            await self._app.bot.send_chat_action(**kwargs)
+        except Exception:
+            logger.debug("Failed to send typing to %s", chat_id)
+
+    async def send(self, msg: OutboundMessage) -> None:
+        if not self._app:
+            return
+        thread_kwargs: dict = {}
+        if msg.thread_id:
+            thread_kwargs["message_thread_id"] = int(msg.thread_id)
+        html = _markdown_to_html(msg.content)
+        chunks = self._split_message(html)
+        for chunk in chunks:
+            try:
+                await self._app.bot.send_message(
+                    chat_id=int(msg.chat_id), text=chunk, parse_mode="HTML",
+                    **thread_kwargs,
+                )
+            except Exception:
+                logger.debug("HTML send failed, falling back to plain text")
+                plain_chunks = self._split_message(msg.content)
+                for pc in plain_chunks:
+                    await self._app.bot.send_message(
+                        chat_id=int(msg.chat_id), text=pc, **thread_kwargs,
+                    )
+                return
+
+    async def start(self) -> None:
+        self._app = Application.builder().token(self._token).build()
+        self._app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self._handle_tg_message))
+        await self._app.initialize()
+        await self._app.start()
+        await self._app.updater.start_polling(
+            allowed_updates=["message"],
+            drop_pending_updates=True,
+        )
+        logger.info("Telegram channel started")
+
+    async def stop(self) -> None:
+        if self._app:
+            await self._app.updater.stop()
+            await self._app.stop()
+            await self._app.shutdown()
+
+    @staticmethod
+    def _split_message(text: str) -> list[str]:
+        if len(text) <= MAX_MESSAGE_LENGTH:
+            return [text]
+        chunks = []
+        while text:
+            if len(text) <= MAX_MESSAGE_LENGTH:
+                chunks.append(text)
+                break
+            split_at = text.rfind("\n", 0, MAX_MESSAGE_LENGTH)
+            if split_at == -1:
+                split_at = MAX_MESSAGE_LENGTH
+            chunks.append(text[:split_at])
+            text = text[split_at:].lstrip("\n")
+        return chunks