nixclaw 0.1.0__tar.gz

nixclaw-0.1.0/LICENSE

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

nixclaw-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: nixclaw
+Version: 0.1.0
+Summary: Multi-agent AI system built on AutoGen for autonomous task execution
+Author: NixClaw
+License: MIT
+Project-URL: Homepage, https://github.com/nixclaw/nixclaw
+Project-URL: Repository, https://github.com/nixclaw/nixclaw
+Keywords: ai,agents,multi-agent,autogen,automation,orchestration,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: autogen-agentchat==0.7.5
+Requires-Dist: autogen-core==0.7.5
+Requires-Dist: autogen-ext[openai]==0.7.5
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: aiofiles>=24.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: aiosqlite>=0.20.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110.0; extra == "api"
+Requires-Dist: uvicorn>=0.27.0; extra == "api"
+Requires-Dist: httpx>=0.27.0; extra == "api"
+Provides-Extra: telegram
+Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
+Provides-Extra: storage
+Requires-Dist: redis>=5.0.0; extra == "storage"
+Provides-Extra: all
+Requires-Dist: nixclaw[api,storage,telegram]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Dynamic: license-file
+
+# NixClaw
+
+Multi-agent AI system built on [AutoGen](https://github.com/microsoft/autogen) for autonomous task execution.
+
+NixClaw breaks down complex tasks, dynamically creates specialized AI agents, and orchestrates them to deliver results — all with human-in-the-loop capabilities via Telegram.
+
+## Installation
+
+```bash
+pip install nixclaw
+```
+
+With optional extras:
+
+```bash
+pip install nixclaw[all]        # Everything (API, Telegram, storage)
+pip install nixclaw[api]        # REST API (FastAPI)
+pip install nixclaw[telegram]   # Telegram bot integration
+pip install nixclaw[storage]    # Database persistence (SQLAlchemy)
+```
+
+## Quick Start
+
+### As a CLI tool
+
+```bash
+# One-shot task
+nixclaw "Analyze the project structure and list all Python files"
+
+# Interactive mode
+nixclaw --interactive
+
+# Team mode with specific agent profiles
+nixclaw --team CodeGenerator,Analyzer "Build a REST API for user management"
+
+# Start REST API server
+nixclaw --serve
+
+# Start Telegram bot
+nixclaw --telegram
+```
+
+### As a Python library
+
+```python
+import asyncio
+from nixclaw import Orchestrator
+
+async def main():
+    orchestrator = Orchestrator()
+    result = await orchestrator.run("Analyze the codebase and find potential bugs")
+    print(result)
+    await orchestrator.close()
+
+asyncio.run(main())
+```
+
+#### Advanced: Direct agent control
+
+```python
+import asyncio
+from nixclaw import AgentFactory
+
+async def main():
+    factory = AgentFactory.get_instance()
+    agent = await factory.create_agent("CodeGenerator")
+    result = await agent.run("Write a Python function to calculate fibonacci numbers")
+    print(agent.get_result_text(result))
+    await factory.cleanup_all()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+Create a `.env` file in your project root:
+
+```env
+# LLM Configuration (required)
+LLM_MODEL=gpt-4
+LLM_API_KEY=your_api_key_here
+LLM_BASE_URL=https://api.openai.com/v1
+
+# Telegram Bot (optional)
+TELEGRAM_BOT_TOKEN=your_bot_token
+TELEGRAM_BOT_TOKEN_LOG=your_log_bot_token
+TELEGRAM_USER_IDS=your_user_id
+
+# Agent Settings
+AGENT_MAX_CONCURRENT_AGENTS=10
+AGENT_ENABLE_REFLECTION=true
+```
+
+See [.env.example](.env.example) for all available options.
+
+## Agent Profiles
+
+NixClaw includes 6 specialist agent profiles:
+
+| Profile | Description |
+|---------|-------------|
+| **CodeGenerator** | Generates, modifies, and refactors code |
+| **Analyzer** | Analyzes code, data, and systems for insights |
+| **Researcher** | Gathers information and synthesizes findings |
+| **SystemAdmin** | Executes system commands and manages infrastructure |
+| **Debugger** | Investigates and fixes bugs systematically |
+| **General** | General-purpose agent for miscellaneous tasks |
+
+## REST API
+
+Start the API server:
+
+```bash
+nixclaw --serve --port 8000
+```
+
+Endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/v1/tasks` | Submit a task |
+| GET | `/api/v1/tasks/{id}` | Get task status |
+| GET | `/api/v1/tasks` | List all tasks |
+| POST | `/api/v1/tasks/{id}/cancel` | Cancel a task |
+| GET | `/api/v1/agents/status` | Agent overview |
+| GET | `/api/v1/health` | Health check |
+
+## Telegram Integration
+
+NixClaw supports two Telegram bots:
+
+- **Primary bot** (`TELEGRAM_BOT_TOKEN`): Receives commands (`/task`, `/status`, `/agents`) and sends task notifications
+- **Log bot** (`TELEGRAM_BOT_TOKEN_LOG`): Mirrors all output from CLI, API, and Telegram to a dedicated log channel
+
+## Architecture
+
+```
+nixclaw/
+├── agents/          # Agent system (orchestrator, factory, profiles)
+├── tools/           # Built-in tools (file ops, shell, search)
+├── core/            # Task manager, context, event bus, retry, security
+├── storage/         # Database persistence (SQLAlchemy + SQLite)
+├── api/             # REST API (FastAPI)
+└── integrations/    # Telegram, webhooks, LLM client
+```
+
+## License
+
+MIT

nixclaw-0.1.0/README.md

@@ -0,0 +1,149 @@
+# NixClaw
+
+Multi-agent AI system built on [AutoGen](https://github.com/microsoft/autogen) for autonomous task execution.
+
+NixClaw breaks down complex tasks, dynamically creates specialized AI agents, and orchestrates them to deliver results — all with human-in-the-loop capabilities via Telegram.
+
+## Installation
+
+```bash
+pip install nixclaw
+```
+
+With optional extras:
+
+```bash
+pip install nixclaw[all]        # Everything (API, Telegram, storage)
+pip install nixclaw[api]        # REST API (FastAPI)
+pip install nixclaw[telegram]   # Telegram bot integration
+pip install nixclaw[storage]    # Database persistence (SQLAlchemy)
+```
+
+## Quick Start
+
+### As a CLI tool
+
+```bash
+# One-shot task
+nixclaw "Analyze the project structure and list all Python files"
+
+# Interactive mode
+nixclaw --interactive
+
+# Team mode with specific agent profiles
+nixclaw --team CodeGenerator,Analyzer "Build a REST API for user management"
+
+# Start REST API server
+nixclaw --serve
+
+# Start Telegram bot
+nixclaw --telegram
+```
+
+### As a Python library
+
+```python
+import asyncio
+from nixclaw import Orchestrator
+
+async def main():
+    orchestrator = Orchestrator()
+    result = await orchestrator.run("Analyze the codebase and find potential bugs")
+    print(result)
+    await orchestrator.close()
+
+asyncio.run(main())
+```
+
+#### Advanced: Direct agent control
+
+```python
+import asyncio
+from nixclaw import AgentFactory
+
+async def main():
+    factory = AgentFactory.get_instance()
+    agent = await factory.create_agent("CodeGenerator")
+    result = await agent.run("Write a Python function to calculate fibonacci numbers")
+    print(agent.get_result_text(result))
+    await factory.cleanup_all()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+Create a `.env` file in your project root:
+
+```env
+# LLM Configuration (required)
+LLM_MODEL=gpt-4
+LLM_API_KEY=your_api_key_here
+LLM_BASE_URL=https://api.openai.com/v1
+
+# Telegram Bot (optional)
+TELEGRAM_BOT_TOKEN=your_bot_token
+TELEGRAM_BOT_TOKEN_LOG=your_log_bot_token
+TELEGRAM_USER_IDS=your_user_id
+
+# Agent Settings
+AGENT_MAX_CONCURRENT_AGENTS=10
+AGENT_ENABLE_REFLECTION=true
+```
+
+See [.env.example](.env.example) for all available options.
+
+## Agent Profiles
+
+NixClaw includes 6 specialist agent profiles:
+
+| Profile | Description |
+|---------|-------------|
+| **CodeGenerator** | Generates, modifies, and refactors code |
+| **Analyzer** | Analyzes code, data, and systems for insights |
+| **Researcher** | Gathers information and synthesizes findings |
+| **SystemAdmin** | Executes system commands and manages infrastructure |
+| **Debugger** | Investigates and fixes bugs systematically |
+| **General** | General-purpose agent for miscellaneous tasks |
+
+## REST API
+
+Start the API server:
+
+```bash
+nixclaw --serve --port 8000
+```
+
+Endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/v1/tasks` | Submit a task |
+| GET | `/api/v1/tasks/{id}` | Get task status |
+| GET | `/api/v1/tasks` | List all tasks |
+| POST | `/api/v1/tasks/{id}/cancel` | Cancel a task |
+| GET | `/api/v1/agents/status` | Agent overview |
+| GET | `/api/v1/health` | Health check |
+
+## Telegram Integration
+
+NixClaw supports two Telegram bots:
+
+- **Primary bot** (`TELEGRAM_BOT_TOKEN`): Receives commands (`/task`, `/status`, `/agents`) and sends task notifications
+- **Log bot** (`TELEGRAM_BOT_TOKEN_LOG`): Mirrors all output from CLI, API, and Telegram to a dedicated log channel
+
+## Architecture
+
+```
+nixclaw/
+├── agents/          # Agent system (orchestrator, factory, profiles)
+├── tools/           # Built-in tools (file ops, shell, search)
+├── core/            # Task manager, context, event bus, retry, security
+├── storage/         # Database persistence (SQLAlchemy + SQLite)
+├── api/             # REST API (FastAPI)
+└── integrations/    # Telegram, webhooks, LLM client
+```
+
+## License
+
+MIT

nixclaw-0.1.0/nixclaw/__init__.py

@@ -0,0 +1,40 @@
+"""NixClaw - Multi-Agent AI System built on AutoGen.
+
+Usage as a library:
+    from nixclaw import Orchestrator, AgentFactory, ManagedAgent
+
+    orchestrator = Orchestrator()
+    result = await orchestrator.run("Your task here")
+
+Usage as CLI:
+    nixclaw "Your task here"
+    nixclaw --interactive
+    python -m nixclaw "Your task here"
+"""
+
+__version__ = "0.1.0"
+
+from nixclaw.agents.orchestrator import Orchestrator
+from nixclaw.agents.agent_factory import AgentFactory
+from nixclaw.agents.base_agent import ManagedAgent, create_model_client
+from nixclaw.agents.agent_profiles import get_profile, list_profiles
+from nixclaw.core.task_manager import TaskManager
+from nixclaw.core.context_manager import ContextManager
+from nixclaw.core.event_bus import EventBus
+from nixclaw.core.async_task_queue import AsyncTaskQueue, get_task_queue
+from nixclaw.config import get_settings
+
+__all__ = [
+    "Orchestrator",
+    "AgentFactory",
+    "ManagedAgent",
+    "create_model_client",
+    "get_profile",
+    "list_profiles",
+    "TaskManager",
+    "ContextManager",
+    "EventBus",
+    "AsyncTaskQueue",
+    "get_task_queue",
+    "get_settings",
+]

nixclaw-0.1.0/nixclaw/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python -m nixclaw"""
+from nixclaw.main import main
+
+main()

nixclaw-0.1.0/nixclaw/agents/agent_factory.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timezone
+
+from nixclaw.agents.base_agent import ManagedAgent, create_model_client
+from nixclaw.agents.agent_profiles import get_profile
+from nixclaw.config import get_settings
+from nixclaw.logger import get_logger
+from nixclaw.storage.models import AgentStatus
+
+logger = get_logger(__name__)
+
+
+class AgentFactory:
+    """Creates, tracks, and manages agent instances.
+
+    Implements the Agent Factory pattern: agents are created on-demand
+    from profiles, tracked for lifecycle management, and cleaned up
+    when no longer needed.
+    """
+
+    _instance: AgentFactory | None = None
+
+    def __init__(self) -> None:
+        self._agents: dict[str, ManagedAgent] = {}
+        self._lock = asyncio.Lock()
+        self._counter: int = 0
+
+    @classmethod
+    def get_instance(cls) -> AgentFactory:
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        cls._instance = None
+
+    def _next_name(self, base: str) -> str:
+        self._counter += 1
+        return f"{base}_{self._counter}"
+
+    async def create_agent(
+        self,
+        profile_name: str,
+        custom_system_message: str | None = None,
+    ) -> ManagedAgent:
+        """Create a new agent from a profile template."""
+        settings = get_settings()
+
+        # Enforce concurrency limit
+        active = sum(
+            1
+            for a in self._agents.values()
+            if a.metadata.status in (AgentStatus.IDLE, AgentStatus.BUSY)
+        )
+        if active >= settings.agent.max_concurrent_agents:
+            raise RuntimeError(
+                f"Max concurrent agents reached ({settings.agent.max_concurrent_agents}). "
+                "Wait for existing agents to complete."
+            )
+
+        profile = get_profile(profile_name)
+        name = self._next_name(profile.name)
+        system_msg = custom_system_message or profile.system_message
+
+        agent = ManagedAgent(
+            name=name,
+            system_message=system_msg,
+            tools=profile.tools,
+            profile=profile_name,
+            description=profile.description,
+        )
+
+        async with self._lock:
+            self._agents[agent.metadata.id] = agent
+
+        logger.info(
+            "Factory created agent: name=%s profile=%s id=%s (active=%d)",
+            name,
+            profile_name,
+            agent.metadata.id,
+            active + 1,
+        )
+        return agent
+
+    async def create_and_run(
+        self,
+        profile_name: str,
+        task: str,
+        context: str = "",
+        priority: str = "normal",
+    ) -> str:
+        """Create a specialist agent, run a task, and return the text result."""
+        agent = await self.create_agent(profile_name)
+
+        full_task = task
+        if context:
+            full_task = f"Context:\n{context}\n\nTask:\n{task}"
+
+        try:
+            result = await agent.run(task=full_task)
+            text = agent.get_result_text(result)
+            logger.info(
+                "Agent '%s' completed task (profile=%s): %.100s...",
+                agent.name,
+                profile_name,
+                text,
+            )
+            return text or "(no output from agent)"
+        except Exception as e:
+            logger.exception("Agent '%s' failed task: %s", agent.name, e)
+            return f"Agent error ({profile_name}): {e}"
+        finally:
+            await self.release_agent(agent.metadata.id)
+
+    async def get_agent(self, agent_id: str) -> ManagedAgent | None:
+        return self._agents.get(agent_id)
+
+    async def release_agent(self, agent_id: str) -> None:
+        """Release an agent and clean up resources."""
+        async with self._lock:
+            agent = self._agents.pop(agent_id, None)
+        if agent:
+            await agent.close()
+            logger.info("Released agent: %s (id=%s)", agent.name, agent_id)
+
+    async def find_idle_agent(self, profile_name: str) -> ManagedAgent | None:
+        """Find an existing idle agent matching the profile."""
+        for agent in self._agents.values():
+            if (
+                agent.metadata.profile == profile_name
+                and agent.metadata.status == AgentStatus.IDLE
+            ):
+                return agent
+        return None
+
+    async def cleanup_all(self) -> None:
+        """Terminate and clean up all agents."""
+        async with self._lock:
+            agents = list(self._agents.values())
+            self._agents.clear()
+        for agent in agents:
+            await agent.close()
+        logger.info("Cleaned up %d agents", len(agents))
+
+    def get_status(self) -> dict:
+        """Get a summary of all agent states."""
+        summary: dict[str, int] = {}
+        for agent in self._agents.values():
+            status = agent.metadata.status.value
+            summary[status] = summary.get(status, 0) + 1
+        return {
+            "total": len(self._agents),
+            "by_status": summary,
+        }

nixclaw-0.1.0/nixclaw/agents/agent_profiles.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Any
+
+from nixclaw.tools.file_operations import read_file, write_file, delete_file
+from nixclaw.tools.directory_ops import list_dir, create_dir
+from nixclaw.tools.search_tools import search_files, search_content
+from nixclaw.tools.shell_executor import execute_shell_command
+
+
+@dataclass
+class AgentProfile:
+    """Template for creating specialized agents."""
+
+    name: str
+    system_message: str
+    description: str
+    tools: list[Callable[..., Any]] = field(default_factory=list)
+
+
+# ── Core tool sets ───────────────────────────────────────────────────────────
+
+FILE_TOOLS: list[Callable[..., Any]] = [read_file, write_file, delete_file]
+DIR_TOOLS: list[Callable[..., Any]] = [list_dir, create_dir]
+SEARCH_TOOLS: list[Callable[..., Any]] = [search_files, search_content]
+SHELL_TOOLS: list[Callable[..., Any]] = [execute_shell_command]
+ALL_TOOLS: list[Callable[..., Any]] = FILE_TOOLS + DIR_TOOLS + SEARCH_TOOLS + SHELL_TOOLS
+
+# ── Pre-defined profiles ────────────────────────────────────────────────────
+
+PROFILES: dict[str, AgentProfile] = {
+    "CodeGenerator": AgentProfile(
+        name="code_generator",
+        description="Generates, modifies, and refactors code",
+        system_message=(
+            "You are an expert code generator. You write clean, efficient, well-structured code. "
+            "You have access to file operations and shell commands. "
+            "When writing code:\n"
+            "- Follow best practices for the language\n"
+            "- Add minimal but clear comments for non-obvious logic\n"
+            "- Handle edge cases and errors\n"
+            "- Use the provided tools to read existing code, write new files, and test your work\n"
+            "Report your results clearly when done."
+        ),
+        tools=ALL_TOOLS,
+    ),
+    "Analyzer": AgentProfile(
+        name="analyzer",
+        description="Analyzes code, data, and systems for insights and issues",
+        system_message=(
+            "You are an expert analyst. You examine code, data, logs, and system state to provide "
+            "clear, actionable insights. You can:\n"
+            "- Read and analyze source code for bugs, patterns, and improvements\n"
+            "- Search codebases for specific patterns or issues\n"
+            "- Analyze command output and logs\n"
+            "- Provide structured analysis with severity levels\n"
+            "Always provide evidence-based conclusions with specific file/line references."
+        ),
+        tools=FILE_TOOLS + DIR_TOOLS + SEARCH_TOOLS,
+    ),
+    "Researcher": AgentProfile(
+        name="researcher",
+        description="Researches topics, gathers information, and synthesizes findings",
+        system_message=(
+            "You are a thorough researcher. You gather information from available sources, "
+            "analyze it, and synthesize clear findings. You can:\n"
+            "- Search files and directories for relevant information\n"
+            "- Read documentation and code to understand systems\n"
+            "- Compile findings into structured summaries\n"
+            "Always cite your sources (file paths, line numbers) and distinguish facts from inferences."
+        ),
+        tools=FILE_TOOLS + DIR_TOOLS + SEARCH_TOOLS,
+    ),
+    "SystemAdmin": AgentProfile(
+        name="system_admin",
+        description="Executes system commands, manages processes and infrastructure",
+        system_message=(
+            "You are an experienced system administrator. You manage system operations safely "
+            "and efficiently. You can:\n"
+            "- Execute shell commands with proper safety checks\n"
+            "- Manage files and directories\n"
+            "- Monitor system state and processes\n"
+            "- Install and configure software\n"
+            "Always explain what commands will do before executing them. "
+            "Prefer safe, reversible operations. Report command output clearly."
+        ),
+        tools=ALL_TOOLS,
+    ),
+    "Debugger": AgentProfile(
+        name="debugger",
+        description="Investigates and fixes bugs, errors, and failures",
+        system_message=(
+            "You are an expert debugger. You systematically identify and fix bugs. Your approach:\n"
+            "1. Reproduce: Understand the error and its context\n"
+            "2. Investigate: Search code, read logs, trace execution paths\n"
+            "3. Diagnose: Identify the root cause with evidence\n"
+            "4. Fix: Apply the minimal correct fix\n"
+            "5. Verify: Test that the fix works\n"
+            "Always explain your reasoning and show evidence for your diagnosis."
+        ),
+        tools=ALL_TOOLS,
+    ),
+    "General": AgentProfile(
+        name="general_assistant",
+        description="General-purpose agent for miscellaneous tasks",
+        system_message=(
+            "You are a capable general-purpose assistant. You handle a variety of tasks "
+            "using the tools available to you. Be concise and effective. "
+            "Use the most appropriate tools for each task and report results clearly."
+        ),
+        tools=ALL_TOOLS,
+    ),
+}
+
+
+def get_profile(name: str) -> AgentProfile:
+    """Get an agent profile by name. Falls back to General if not found."""
+    profile = PROFILES.get(name)
+    if profile is None:
+        profile = PROFILES["General"]
+    return profile
+
+
+def list_profiles() -> list[str]:
+    """List all available profile names."""
+    return list(PROFILES.keys())