Models

from cmdop_bot import Model
 
# Available tiers (cheapest to most capable)
# Each tier returns a model string that SDKRouter resolves to an actual LLM
Model.cheap()      # "@cheap+agents"    — Most economical
Model.budget()     # "@budget+agents"   — Budget-friendly
Model.fast()       # "@fast+agents"     — Fastest response
Model.standard()   # "@standard+agents" — Standard performance
Model.balanced()   # "@balanced+agents" — Best value (default)
Model.smart()      # "@smart+agents"    — Highest quality
Model.premium()    # "@premium+agents"  — Premium tier

# Pass vision=True or code=True to enable extra capabilities on any tier
Model.smart(vision=True)   # "@smart+agents+vision"   — image understanding
Model.balanced(code=True)  # "@balanced+agents+code"   — code generation
Model.fast(vision=True, code=True)  # "@fast+agents+vision+code" — both capabilities

from cmdop_bot import Model
from cmdop_bot.channels.telegram import TelegramBot
 
# Pass the model tier to the bot constructor via the model parameter
bot = TelegramBot(
    token="...",
    cmdop_api_key="...",
    model=Model.cheap(),  # Use cheapest model for all /agent commands
)

from cmdop_bot.models import User
 
# Create a User with channel-specific ID and optional profile fields
user = User(
    id="123456789",
    channel="telegram",
    username="john_doe",
    display_name="John Doe",
    is_admin=False,  # Set to True for admin privileges
)
 
user.unique_id  # "telegram:123456789" — combines channel + id
user.name       # "John Doe" (best available: display_name > username > id)

from cmdop_bot.models import Message, User
 
# Create a Message linking a User to their text input in a specific chat
msg = Message(
    id="msg_123",
    channel="telegram",
    chat_id="456",                                  # Chat/conversation ID
    user=User(id="789", channel="telegram"),         # Author of the message
    text="/shell ls -la",                            # Raw message text
)

from cmdop_bot.models import Command
 
# Parse a slash-command string into a structured Command object
cmd = Command.parse("/shell ls -la")
# cmd.name = "shell"          — command name without the "/" prefix
# cmd.args = ["ls", "-la"]    — parsed argument list
# cmd.args_text = "ls -la"    — arguments as a single string
# cmd.raw_text = "/shell ls -la"  — original full text
 
# Returns None when the text is not a command (no "/" prefix)
cmd = Command.parse("just a message")  # None

from cmdop_bot.models import Permission, PermissionLevel
 
# Define a per-user, per-machine permission with an optional command whitelist
perm = Permission(
    user_id="telegram:123456789",
    machine="prod-server",
    level=PermissionLevel.EXECUTE,
    allowed_commands=["shell", "ls"],  # Only these commands are permitted
    denied_commands=None,               # No explicit denials
)
 
perm.can_execute("shell")  # True — in the allowed list
perm.can_execute("agent")  # False — not in the allowed list

from cmdop_bot.models import PermissionLevel
 
# Enum values — higher value means more access
PermissionLevel.NONE     # 0   — no access
PermissionLevel.READ     # 10  — view status and read files
PermissionLevel.EXECUTE  # 20  — run shell commands
PermissionLevel.FILES    # 30  — write and delete files
PermissionLevel.ADMIN    # 100 — full unrestricted access

# Top-level imports — common errors you'll catch in bot code
from cmdop_bot import (
    IntegrationError,      # Base class for all cmdop-bot errors
    ChannelError,          # Channel-specific error (Telegram, Discord, etc.)
    PermissionDeniedError, # Raised when a user lacks required permissions
    ConfigurationError,    # Raised for invalid bot configuration
)
 
# Additional exceptions available from the exceptions module
from cmdop_bot.exceptions import (
    RateLimitError,        # Raised when API rate limit is exceeded
    ConnectionError,       # Raised when gRPC connection to agent fails
)