nullabot 1.0.1__py3-none-any.whl

nullabot/core/state.py

@@ -0,0 +1,214 @@
+"""
+State Management - Never lose progress.
+
+Handles checkpointing, state persistence, and crash recovery.
+"""
+
+import json
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class AgentType(str, Enum):
+    """Types of agents available."""
+
+    THINKER = "thinker"
+    DESIGNER = "designer"
+    CODER = "coder"
+
+
+class AgentStatus(str, Enum):
+    """Current status of an agent."""
+
+    IDLE = "idle"  # Not running
+    RUNNING = "running"  # Actively working
+    PAUSED = "paused"  # User requested pause
+    BLOCKED = "blocked"  # Needs user input
+    ERROR = "error"  # Encountered error
+
+
+class Message(BaseModel):
+    """A single message in conversation history."""
+
+    role: str  # "user", "assistant", "system"
+    content: str
+    timestamp: datetime = Field(default_factory=datetime.now)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Checkpoint(BaseModel):
+    """
+    Checkpoint - saved state that survives crashes.
+
+    Contains everything needed to resume work exactly where agent left off.
+    """
+
+    # Identity
+    agent_type: AgentType
+    project_name: str
+
+    # Current task
+    task: str  # What user asked for
+    task_context: str = ""  # Additional context
+
+    # Progress
+    current_step: str = ""  # What agent is doing now
+    completed_steps: list[str] = Field(default_factory=list)
+    next_steps: list[str] = Field(default_factory=list)
+
+    # Outputs created
+    outputs: list[str] = Field(default_factory=list)  # File paths
+
+    # Thinking (agent's internal notes)
+    thoughts: str = ""
+    learnings: list[str] = Field(default_factory=list)
+
+    # Metadata
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+    cycle_count: int = 0  # How many think cycles completed
+
+    def save(self, path: Path) -> None:
+        """Save checkpoint to file."""
+        self.updated_at = datetime.now()
+        path.write_text(self.model_dump_json(indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: Path) -> Optional["Checkpoint"]:
+        """Load checkpoint from file if exists."""
+        if not path.exists():
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return cls.model_validate(data)
+        except Exception:
+            return None
+
+
+class AgentState(BaseModel):
+    """
+    Full agent state including runtime information.
+    """
+
+    # Core
+    agent_type: AgentType
+    status: AgentStatus = AgentStatus.IDLE
+    project_name: str
+
+    # Current checkpoint
+    checkpoint: Optional[Checkpoint] = None
+
+    # Conversation
+    messages: list[Message] = Field(default_factory=list)
+
+    # Runtime
+    started_at: Optional[datetime] = None
+    error_count: int = 0
+    last_error: Optional[str] = None
+
+    # User interaction
+    pending_question: Optional[str] = None  # Question waiting for user
+    pending_options: list[str] = Field(default_factory=list)
+
+    # === Ralph-inspired reliability features ===
+
+    # Circuit breaker state
+    circuit_state: str = "closed"  # closed, open, half_open
+    circuit_failure_count: int = 0
+    circuit_last_failure: Optional[datetime] = None
+
+    # Progress tracking
+    cycles_without_progress: int = 0
+    last_output_hash: Optional[str] = None
+    completion_signals: int = 0
+    total_cycles: int = 0
+
+    # Rate limiting stats
+    total_tokens_used: int = 0
+    total_requests: int = 0
+    rate_limited_waits: int = 0
+    total_wait_time_seconds: float = 0.0
+
+    # Exit detection
+    exit_reason: Optional[str] = None
+    explicit_exit_signal: bool = False
+
+    def save(self, path: Path) -> None:
+        """Save state to file."""
+        path.write_text(self.model_dump_json(indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: Path) -> Optional["AgentState"]:
+        """Load state from file if exists."""
+        if not path.exists():
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return cls.model_validate(data)
+        except Exception:
+            return None
+
+    def add_message(self, role: str, content: str, **metadata: Any) -> None:
+        """Add message to history."""
+        self.messages.append(Message(role=role, content=content, metadata=metadata))
+
+    def start(self) -> None:
+        """Mark agent as running."""
+        self.status = AgentStatus.RUNNING
+        self.started_at = datetime.now()
+        self.error_count = 0
+
+    def pause(self) -> None:
+        """Mark agent as paused (user requested)."""
+        self.status = AgentStatus.PAUSED
+
+    def block(self, question: str, options: list[str] | None = None) -> None:
+        """Mark agent as blocked, waiting for user input."""
+        self.status = AgentStatus.BLOCKED
+        self.pending_question = question
+        self.pending_options = options or []
+
+    def unblock(self, answer: str) -> None:
+        """Resume after user provides input."""
+        self.add_message("user", answer)
+        self.status = AgentStatus.RUNNING
+        self.pending_question = None
+        self.pending_options = []
+
+    def error(self, message: str) -> None:
+        """Record an error."""
+        self.error_count += 1
+        self.last_error = message
+        if self.error_count >= 3:
+            self.status = AgentStatus.ERROR
+
+
+class HistoryWriter:
+    """Append-only history writer for crash safety."""
+
+    def __init__(self, path: Path):
+        self.path = path
+
+    def append(self, message: Message) -> None:
+        """Append message to history file."""
+        with open(self.path, "a", encoding="utf-8") as f:
+            f.write(message.model_dump_json() + "\n")
+
+    def load_all(self) -> list[Message]:
+        """Load all messages from history."""
+        if not self.path.exists():
+            return []
+        messages = []
+        with open(self.path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        messages.append(Message.model_validate_json(line))
+                    except Exception:
+                        continue
+        return messages

nullabot-1.0.1.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: nullabot
+Version: 1.0.1
+Summary: 24/7 AI agents that think, design, and code - controlled via Telegram
+Project-URL: Homepage, https://github.com/ebokoo/nullabot
+Project-URL: Repository, https://github.com/ebokoo/nullabot
+Project-URL: Issues, https://github.com/ebokoo/nullabot/issues
+Author: ebokoo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,automation,bot,claude,coding,telegram
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-telegram-bot>=21.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: watchdog>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Nullabot
+
+24/7 AI agents that think, design, and code - controlled via Telegram.
+
+## Requirements
+
+1. **Python 3.11+**
+2. **Claude Code CLI** (requires Claude Max subscription ~$100-200/month)
+   ```bash
+   npm install -g @anthropic-ai/claude-code
+   claude login
+   ```
+
+## Install
+
+```bash
+pip install nullabot
+nullabot setup
+```
+
+The setup wizard asks for:
+- **Bot token** - Create at [@BotFather](https://t.me/BotFather) on Telegram
+- **Your user ID** - Get from [@userinfobot](https://t.me/userinfobot) on Telegram
+- **Other users** (optional) - Friends who can use your bot
+
+## Start the Bot
+
+```bash
+nullabot bot
+```
+
+Now open Telegram and message your bot!
+
+## Telegram Commands
+
+| Command | Description |
+|---------|-------------|
+| `/start` | Show main menu |
+| `/usage` | Show project costs |
+| `/rules` | View/add global rules |
+| `/chat <question>` | Ask anything |
+| `/help` | All commands |
+
+**Admin commands:**
+| Command | Description |
+|---------|-------------|
+| `/users` | List all users |
+| `/approve <id>` | Approve a user |
+| `/revoke <id>` | Remove user |
+
+## CLI Commands
+
+```bash
+nullabot new myproject              # Create project
+nullabot think myproject "task"     # Research agent
+nullabot design myproject "task"    # Design agent
+nullabot code myproject "task"      # Coding agent
+nullabot projects                   # List projects
+nullabot usage                      # Show costs
+```
+
+## Three Agents
+
+| Agent | What it does |
+|-------|--------------|
+| **Thinker** | Research, analyze, brainstorm |
+| **Designer** | UI/UX specs, component design |
+| **Coder** | Write code, tests, docs |
+
+Agents automatically hand off context to each other.
+
+## Global Rules
+
+Tell agents what to always/never do:
+
+```
+/rules add do Always use TypeScript
+/rules add dont Never use console.log
+```
+
+Or just say it naturally in any message - it auto-saves!
+
+## Run 24/7
+
+```bash
+# Manual (stops when terminal closes)
+./run_nullabot.sh bot
+
+# Auto-start on Mac login
+./setup_autostart.sh
+```
+
+## License
+
+MIT

nullabot-1.0.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+nullabot/__init__.py,sha256=96923LhB3uU4TE33GdjyG8M2fRRcqeWvRWlqxt48OV4,58
+nullabot/cli.py,sha256=zattwGYh4feT_sRjCxSOoG6WSToxc_F1Zp00T_zrAIU,25800
+nullabot/agents/__init__.py,sha256=6mE-zjqFa99WfnE-khjDpCSKzaNlukKVP7tB5Q4o7Vk,133
+nullabot/agents/claude_agent.py,sha256=P67S7UlIjKPInYcZcIGOp7o5shA3VLiv96auupvfPs8,30483
+nullabot/bot/__init__.py,sha256=9axCMJfCE09CxMGsxtx81QZcBEXfz6wruHbYEtQQAeY,102
+nullabot/bot/telegram.py,sha256=5YNpm2OGzy5A8jHEyvuVFvq9MTYeQ9qB8qFjiYQ_cYw,68354
+nullabot/core/__init__.py,sha256=Yn9zEFXF_2-aXiiU_iftYuaXWrX1qC7ZaEd6i3sarIE,314
+nullabot/core/claude_code.py,sha256=sIKINJzjolBBpd2B_XhM6Egwmxs8E_VvDV3AOcuJbkw,9306
+nullabot/core/memory.py,sha256=0Qh9WRTZIkdOfGVLsAUbHIAuoFZ9-CoZ9wgP5DiPR7E,30674
+nullabot/core/project.py,sha256=FZofBZzIhMQUCXxCI4jjJZjKRr5u4iJUbor70tvLh7Q,6222
+nullabot/core/rate_limiter.py,sha256=41CF4cX_n5_PFc6Uk1vp6m4MERxXl25p1wyw2FVdgsM,16693
+nullabot/core/reliability.py,sha256=nfMN29dCQqM_T_MSLe0z9Tk0N5CWYFtmNXVe9Lqmiyw,13985
+nullabot/core/sandbox.py,sha256=fWgjhWglGzXsJ10qxiKwJEkQQv6tLVa-DsshO7qcQvQ,4562
+nullabot/core/state.py,sha256=yeFF4r3h0nRd5LENiXE7SSqfWPuljGy7X0FgE_GuI5o,6307
+nullabot-1.0.1.dist-info/METADATA,sha256=38vnwVRA7YqMgmjyLWVV6zVl95IkepRlUK1nD10nX8A,3360
+nullabot-1.0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+nullabot-1.0.1.dist-info/entry_points.txt,sha256=lHaTGUU4ku7Q6ZRZnlpp5LrHRyLxhaRB9HzXzsJwYY8,47
+nullabot-1.0.1.dist-info/licenses/LICENSE,sha256=IppsK7DD3SKtJlMoquzr1-bGKs88x85956yPxCn8H-U,1063
+nullabot-1.0.1.dist-info/RECORD,,

nullabot-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nullabot-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nullabot = nullabot.cli:main

nullabot-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ebokoo
+
+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.