openbotx 0.0.1__tar.gz

openbotx-0.0.1/LICENSE

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

openbotx-0.0.1/PKG-INFO

@@ -0,0 +1,382 @@
+Metadata-Version: 2.4
+Name: openbotx
+Version: 0.0.1
+Summary: Your Personal AI assistant for any OS and any platform
+Author-email: Paulo Coutinho <paulocoutinhox@gmail.com>
+Maintainer-email: Paulo Coutinho <paulocoutinhox@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/openbotx/openbotx
+Project-URL: Repository, https://github.com/openbotx/openbotx
+Project-URL: Documentation, https://github.com/openbotx/openbotx
+Project-URL: Bug Tracker, https://github.com/openbotx/openbotx/issues
+Keywords: ai,agent,assistant,personal,bot,llm,pydantic,pydantic-ai,skills,chatbot,telegram,websocket,mcp,anthropic,openai
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-ai>=1.50.0
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: fastapi>=0.128.0
+Requires-Dist: uvicorn[standard]>=0.40.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: sqlalchemy>=2.0.46
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: websockets<16.0
+Requires-Dist: python-telegram-bot>=22.6
+Requires-Dist: anthropic>=0.77.0
+Requires-Dist: openai>=2.16.0
+Requires-Dist: apscheduler>=3.11.2
+Requires-Dist: faster-whisper>=1.2.1
+Requires-Dist: soundfile>=0.13.1
+Requires-Dist: pillow>=11.0.0
+Requires-Dist: boto3>=1.42.38
+Requires-Dist: mcp>=1.26.0
+Requires-Dist: tiktoken>=0.12.0
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: click>=8.3.1
+Requires-Dist: rich>=14.3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.14.14; extra == "dev"
+Requires-Dist: mypy>=1.19.1; extra == "dev"
+Requires-Dist: build>=1.4.0; extra == "dev"
+Requires-Dist: twine>=6.2.0; extra == "dev"
+Dynamic: license-file
+
+# OpenBotX — Personal AI Assistant
+
+<p align="center">
+    <a href="https://github.com/openbotx/openbotx" target="_blank" rel="noopener noreferrer">
+        <img width="280" src="extras/images/logo.png" alt="OpenBotX Logo">
+    </a>
+</p>
+
+<p align="center">
+    <a href="https://badge.fury.io/py/openbotx" target="_blank" rel="noopener noreferrer">
+        <img src="https://badge.fury.io/py/openbotx.svg" alt="PyPI version">
+    </a>
+    <a href="https://www.python.org/downloads/" target="_blank" rel="noopener noreferrer">
+        <img src="https://img.shields.io/badge/python-3.11--3.13-blue.svg" alt="Python 3.11-3.13">
+    </a>
+    <a href="https://opensource.org/licenses/MIT" target="_blank" rel="noopener noreferrer">
+        <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+    </a>
+</p>
+
+<p align="center">
+OpenBotX is a Python-based personal AI assistant powered by artificial intelligence.
+It uses skills to define behavior, tools to execute actions, gateways for communication, and providers to connect external services and AI models.
+</p>
+
+## Features
+
+- **Multiple Gateways**: CLI, WebSocket, Telegram, HTTP API
+- **Skills System**: Define AI capabilities in Markdown files
+- **Unlimited Tools**: Register Python functions as tools for the AI
+- **MCP Support**: Model Context Protocol integration
+- **Scheduling**: Cron jobs and one-time scheduled tasks
+- **Memory**: Persistent conversation history per channel
+- **Security**: Built-in prompt injection detection
+- **API**: Full REST API for all operations
+- **Providers**: Modular architecture - LLM, storage, database, transcription, TTS
+
+## Installation
+
+### Prerequisites
+
+**Python Version:** This project requires Python 3.11 to 3.13 (3.14 is not yet supported due to dependencies).
+
+Install [uv](https://github.com/astral-sh/uv) - a fast Python package installer and resolver:
+
+```bash
+# macOS/Linux (recommended)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# macOS with Homebrew
+brew install uv
+
+# Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Or with pipx (if you have it)
+pipx install uv
+```
+
+### From PyPI (Users)
+
+```bash
+# Install globally as a tool (recommended)
+uv tool install openbotx
+
+# Or install in current environment
+uv pip install openbotx
+```
+
+**All features included**: Telegram, Audio (Whisper), S3, MCP, Screenshot, and more.
+
+### From Source (Developers)
+
+```bash
+# Clone and setup
+git clone https://github.com/openbotx/openbotx.git
+cd openbotx
+make setup
+
+# Activate virtual environment
+source .venv/bin/activate
+```
+
+## Quick Start
+
+### For Users (after installation)
+
+```bash
+# Create a new project from starter template
+mkdir my-bot
+cd my-bot
+openbotx init
+
+# Edit .env file in your project directory
+nano .env
+
+# Start the bot in CLI mode
+openbotx start --cli-mode
+
+# Or start the API server
+openbotx start
+```
+
+The starter template includes:
+- Pre-configured `config.yml` with basic data
+- Example skills in the `skills/` directory
+- Environment template (`.env.example`)
+- Ready-to-use folder structure
+
+### For Developers (from source)
+
+```bash
+# First time setup
+make setup
+
+# Activate virtual environment
+source .venv/bin/activate
+
+# Create a project with the starter template
+mkdir my-project
+cd my-project
+openbotx init
+
+# Edit .env file in your project directory
+nano .env
+
+# Start the bot in CLI mode
+openbotx start --cli-mode
+
+# Or start the API server
+openbotx start
+```
+
+## Project Structure
+
+### Package Structure
+
+```
+openbotx/
+├── openbotx/               # Main package (library code)
+│   ├── core/               # Core components (orchestrator, message bus, etc.)
+│   ├── providers/          # Provider implementations (LLM, gateway, storage)
+│   ├── api/                # FastAPI REST API
+│   ├── cli/                # CLI commands
+│   ├── models/             # Pydantic data models
+│   ├── agent/              # PydanticAI agent
+│   └── tools/              # Built-in tools
+├── docs/                   # Documentation
+├── tests/                  # Test suite
+├── pyproject.toml          # Package configuration
+├── Makefile                # Development commands
+└── README.md
+```
+
+## Configuration
+
+When you run `openbotx init`, it creates a `config.yml`:
+
+```yaml
+version: "1.0.0"
+
+bot:
+  name: "My Assistant"
+  description: "AI Assistant powered by OpenBotX"
+
+llm:
+  provider: "anthropic"  # Any PydanticAI supported provider
+  model: "claude-sonnet-4-20250514"
+  # Optional: max_tokens, temperature, top_p, timeout, etc
+
+gateways:
+  cli:
+    enabled: true
+  websocket:
+    enabled: true
+    port: 8765
+  telegram:
+    enabled: false
+    token: "${TELEGRAM_BOT_TOKEN}"
+    allowed_users: []
+
+api:
+  host: "0.0.0.0"
+  port: 8000
+```
+
+## Creating Skills
+
+OpenBotX includes **native skills** (like `screenshot`) built into the package. You can also create custom skills in your project's `skills/` directory, and these can override native skills.
+
+Skills are Markdown files with YAML frontmatter:
+
+```markdown
+---
+name: code-review
+description: Review code for quality and best practices
+version: "1.0.0"
+triggers:
+  - review code
+  - code review
+  - check my code
+tools:
+  - read_file
+---
+
+# Code Review Skill
+
+## Steps
+1. Read the code file(s) provided
+2. Analyze for common issues
+3. Check coding standards
+4. Suggest improvements
+
+## Guidelines
+- Be constructive, not critical
+- Explain why changes are suggested
+- Prioritize security issues
+```
+
+## Creating Tools
+
+Tools are Python functions that the AI can call:
+
+```python
+from openbotx.core.tools_registry import tool
+
+@tool(
+    name="calculate",
+    description="Perform mathematical calculations",
+)
+def tool_calculate(expression: str) -> str:
+    """Calculate a math expression."""
+    return str(eval(expression))
+```
+
+## CLI Commands
+
+```bash
+openbotx init               # Initialize from starter template
+openbotx init --force       # Overwrite existing files
+openbotx start              # Start the API server
+openbotx start --cli-mode   # Start in interactive CLI mode
+openbotx status             # Show server status
+openbotx skills list        # List all skills
+openbotx providers list     # List all providers
+openbotx send "Hello!"      # Send a message
+openbotx config             # Show configuration
+openbotx version            # Show version
+```
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /api/messages` | Send a message |
+| `GET /api/skills` | List all skills |
+| `GET /api/tools` | List all tools |
+| `GET /api/providers` | List providers |
+| `POST /api/scheduler/cron` | Create cron job |
+| `GET /api/memory/{channel}` | Get conversation history |
+| `GET /api/system/health` | Health check |
+
+## Development Commands (Makefile)
+
+```bash
+# Setup & Installation
+make setup          # First time setup with uv (venv + deps)
+make dev-install    # Install in editable mode with dev dependencies
+make install        # Install in production mode
+
+# Testing & Quality
+make test           # Run tests
+make test-cov       # Run tests with coverage
+make lint           # Run linter
+make format         # Format code
+make check          # Run all checks (lint + type check)
+
+# Building & Publishing
+make build          # Build package
+make publish-test   # Publish to TestPyPI
+make publish        # Publish to PyPI
+
+# Versioning
+make version        # Show current version
+make bump-patch     # Bump patch version (0.0.X)
+make bump-minor     # Bump minor version (0.X.0)
+make bump-major     # Bump major version (X.0.0)
+
+# Cleanup
+make clean          # Clean build artifacts
+make clean-venv     # Remove virtual environment
+make reset          # Reset environment (clean venv + setup)
+```
+
+## Architecture
+
+```
+Gateway → MessageBus → Orchestrator → Agent → Response → Gateway
+              ↓              ↓
+           Security      Skills/Tools
+              ↓              ↓
+           Context        Memory
+```
+
+**Providers:**
+- **LLM**: Multiple providers supported (see [Configuration](docs/configuration.md))
+- **Gateway**: CLI, WebSocket, Telegram, HTTP
+- **Storage**: Local filesystem, S3
+- **Database**: SQLite
+- **Scheduler**: Cron, one-time schedules
+- **Transcription**: Multiple providers supported
+- **TTS**: Multiple providers supported
+
+## Documentation
+
+For detailed documentation, see:
+
+- [Configuration](docs/configuration.md) - Complete configuration reference
+- [Architecture](docs/architecture.md) - System design and components
+- [API Reference](docs/api.md) - Complete REST API documentation
+- [Skills](docs/skills.md) - Creating and managing skills
+- [Tools](docs/tools.md) - Creating custom tools
+- [Security](docs/security.md) - Security features and best practices
+- [Providers](docs/providers/) - Gateway and provider implementations
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Documentation](https://github.com/openbotx/openbotx)
+- [GitHub](https://github.com/openbotx/openbotx)
+- [PyPI](https://pypi.org/project/openbotx/)