matraca 0.1.0__tar.gz

matraca-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.3
+Name: matraca
+Version: 0.1.0
+Summary: Agente de IA pessoal para Telegram e WhatsApp, com suporte a múltiplos provedores de modelos e sistema de habilidades extensível.
+Keywords: ai,agent,telegram,whatsapp,chatbot,llm,pydantic-ai
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: uv
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-ai-slim[google,anthropic,openai,groq,mistral,cohere,openrouter]>=1.63.0
+Requires-Dist: pydantic-deep>=0.2.17
+Requires-Dist: python-telegram-bot>=22.6
+Requires-Dist: websockets>=15.0.1
+Requires-Python: >=3.13, <3.14
+Description-Content-Type: text/markdown
+
+# Matraca
+
+Agente de inteligência artificial para **Telegram** e **WhatsApp**. Roda no seu computador, você usa pelos apps dos canais.
+
+Você pode usar com qualquer provedor e modelo suportado pelo PydanticAI. Tem memória persistente, pesquisa na web, acesso a arquivos e sistema de habilidades extensível via scripts Python.
+
+## Instalação
+
+Requer Python 3.13 e [uv](https://docs.astral.sh/uv/). [Node.js](https://nodejs.org/) é necessário para o canal WhatsApp.
+
+```bash
+uv tool install matraca
+```
+
+## Uso
+
+```bash
+matraca telegram   # inicia o canal Telegram
+matraca whatsapp   # inicia o canal WhatsApp
+```
+
+Na primeira execução, o arquivo de configuração é criado em `~/.matraca/config.json`. Adicione as chaves do provedor escolhido e o token do bot (se Telegram) antes de iniciar.
+
+## Habilidades
+
+Habilidades são scripts Python que ampliam o agente. Instale-as em `~/.matraca/skills/` — cada uma é uma pasta com um `SKILL.md` e scripts em `scripts/`.
+
+## Licença
+
+MIT

matraca-0.1.0/README.md

@@ -0,0 +1,30 @@
+# Matraca
+
+Agente de inteligência artificial para **Telegram** e **WhatsApp**. Roda no seu computador, você usa pelos apps dos canais.
+
+Você pode usar com qualquer provedor e modelo suportado pelo PydanticAI. Tem memória persistente, pesquisa na web, acesso a arquivos e sistema de habilidades extensível via scripts Python.
+
+## Instalação
+
+Requer Python 3.13 e [uv](https://docs.astral.sh/uv/). [Node.js](https://nodejs.org/) é necessário para o canal WhatsApp.
+
+```bash
+uv tool install matraca
+```
+
+## Uso
+
+```bash
+matraca telegram   # inicia o canal Telegram
+matraca whatsapp   # inicia o canal WhatsApp
+```
+
+Na primeira execução, o arquivo de configuração é criado em `~/.matraca/config.json`. Adicione as chaves do provedor escolhido e o token do bot (se Telegram) antes de iniciar.
+
+## Habilidades
+
+Habilidades são scripts Python que ampliam o agente. Instale-as em `~/.matraca/skills/` — cada uma é uma pasta com um `SKILL.md` e scripts em `scripts/`.
+
+## Licença
+
+MIT

matraca-0.1.0/app/agent.py

@@ -0,0 +1,151 @@
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+
+from pydantic_ai import Agent, RunContext
+from pydantic_ai.agent import EventStreamHandler
+from pydantic_deep import (
+    LocalBackend,
+    create_sliding_window_processor,
+)
+
+from app.deps import MatracaDeps
+from app.history import HistoryManager
+from app.models import LoggingModel, build_model
+from app.setup import MatracaConfig, MatracaSetup
+from app.tools import (
+    configure_console_toolset,
+    configure_file_toolset,
+    configure_memory_toolset,
+    configure_plan_toolset,
+    configure_skills_toolset,
+    configure_todo_toolset,
+    configure_web_fetch_tool,
+)
+from app.tools.web_search import configure_search_tool
+
+
+def build_dependencies(
+    setup: MatracaSetup,
+    user_id: str | int = "default",
+    allowed_directories: list[str] | None = None,
+    enable_execute: bool = False,
+    ask_user: Callable[[str, list[dict[str, str]]], Awaitable[str]] | None = None,
+    send_file: Callable[[str, bytes], Awaitable[None]] | None = None,
+) -> MatracaDeps:
+    workspace_dir = setup.paths.user_workspace(user_id)
+    all_dirs = [str(workspace_dir)] + (allowed_directories or [])
+
+    backend = LocalBackend(
+        root_dir=workspace_dir,
+        allowed_directories=all_dirs,
+        enable_execute=enable_execute,
+        ask_fallback="deny",
+    )
+
+    return MatracaDeps(
+        backend=backend,
+        workspace_dir=workspace_dir,
+        ask_user=ask_user,
+        send_file=send_file,
+    )
+
+
+def create_chat_agent(
+    config: MatracaConfig,
+    instructions: str,
+    skills_dir: Path,
+    enable_execute: bool = False,
+    tools: dict[str, bool] | None = None,
+    request_log_dir: Path | None = None,
+) -> Agent[MatracaDeps, str]:
+
+    model = build_model(config)
+    if request_log_dir:
+        model = LoggingModel(model, request_log_dir)
+
+    agent: Agent[MatracaDeps, str] = Agent(
+        model,
+        deps_type=MatracaDeps,
+        retries=2,
+        history_processors=[
+            create_sliding_window_processor(
+                trigger=("tokens", 200_000),
+                keep=("tokens", 125_000),
+            )
+        ],
+    )
+
+    @agent.instructions
+    async def _agent_instructions(_ctx: RunContext[MatracaDeps]) -> str:  # pyright: ignore[reportUnusedFunction]
+        return instructions
+
+    enabled_tools = {
+        "memory": True,
+        "todo": True,
+        "console": True,
+        "web_search": True,
+        "web_fetch": True,
+        "skills": True,
+        "plan": True,
+        "files": True,
+    }
+
+    if tools:
+        for name in enabled_tools:
+            if name in tools:
+                enabled_tools[name] = bool(tools[name])
+
+    if enabled_tools["memory"]:
+        agent = configure_memory_toolset(agent)
+    if enabled_tools["todo"]:
+        agent = configure_todo_toolset(agent)
+    if enabled_tools["console"]:
+        agent = configure_console_toolset(agent, enable_execute=enable_execute)
+    if enabled_tools["web_search"]:
+        agent = configure_search_tool(agent, api_key=config.models.google_api_key)
+    if enabled_tools["web_fetch"]:
+        agent = configure_web_fetch_tool(agent)
+    if enabled_tools["skills"]:
+        agent = configure_skills_toolset(agent, skills_dir=skills_dir)
+    if enabled_tools["plan"]:
+        agent = configure_plan_toolset(agent)
+    if enabled_tools["files"]:
+        agent = configure_file_toolset(agent)
+
+    return agent
+
+
+async def run_agent_interaction(
+    agent: Agent[MatracaDeps, str],
+    user_input: str,
+    user_id: str | int,
+    setup: MatracaSetup,
+    history_manager: HistoryManager,
+    history_path: Path,
+    allowed_directories: list[str] | None = None,
+    enable_execute: bool = False,
+    event_stream_handler: EventStreamHandler[MatracaDeps] | None = None,
+    ask_user: Callable[[str, list[dict[str, str]]], Awaitable[str]] | None = None,
+    send_file: Callable[[str, bytes], Awaitable[None]] | None = None,
+) -> str:
+    deps = build_dependencies(
+        setup=setup,
+        user_id=user_id,
+        allowed_directories=allowed_directories,
+        enable_execute=enable_execute,
+        ask_user=ask_user,
+        send_file=send_file,
+    )
+
+    history = history_manager.load(history_path)
+
+    response = await agent.run(
+        user_input,
+        deps=deps,
+        message_history=history,
+        event_stream_handler=event_stream_handler,
+    )
+
+    history_manager.save(history_path, response.all_messages())
+
+    return response.output

matraca-0.1.0/app/channels/telegram/__init__.py

@@ -0,0 +1,3 @@
+from app.channels.telegram.bot import run_telegram
+
+__all__ = ["run_telegram"]

matraca-0.1.0/app/channels/telegram/ask_user.py

@@ -0,0 +1,90 @@
+import asyncio
+import logging
+from collections.abc import Callable, Coroutine
+
+from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
+from telegram.ext import ContextTypes
+
+logger = logging.getLogger(__name__)
+
+_pending_asks: dict[int, tuple[asyncio.Future[str], list[dict[str, str]]]] = {}
+
+
+def make_ask_user_callback(
+    user_id: int, update: Update
+) -> Callable[[str, list[dict[str, str]]], Coroutine[object, object, str]]:
+    async def ask_user(question: str, options: list[dict[str, str]]) -> str:
+        if update.message is None:
+            return options[0]["label"] if options else ""
+
+        keyboard = InlineKeyboardMarkup(
+            [
+                [InlineKeyboardButton(opt["label"], callback_data=str(i))]
+                for i, opt in enumerate(options)
+            ]
+        )
+        _ = await update.message.reply_text(question, reply_markup=keyboard)
+
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[str] = loop.create_future()
+        _pending_asks[user_id] = (future, options)
+
+        logger.info(
+            "[ask_user] pergunta enviada para user_id=%d; pending_asks keys=%s",
+            user_id,
+            list(_pending_asks),
+        )
+        result = await future
+        logger.info("[ask_user] future resolvida para user_id=%d com valor=%r", user_id, result)
+        return result
+
+    return ask_user
+
+
+def resolve_pending_text_response(user_id: int, text: str) -> bool:
+    entry = _pending_asks.pop(user_id, None)
+    if entry is None:
+        return False
+
+    future, _options = entry
+    if future.done():
+        return True
+
+    future.set_result(text)
+    return True
+
+
+async def handle_callback_query(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    _ = context
+    query = update.callback_query
+    if query is None:
+        return
+
+    _ = await query.answer()
+    user_id = query.from_user.id
+
+    logger.info(
+        "[callback_query] recebido user_id=%d data=%r; pending_asks keys=%s",
+        user_id,
+        query.data,
+        list(_pending_asks),
+    )
+
+    entry = _pending_asks.pop(user_id, None)
+    if entry is None:
+        logger.warning("[callback_query] nenhuma future pendente para user_id=%d", user_id)
+        return
+
+    future, options = entry
+    if future.done():
+        logger.warning("[callback_query] future já concluída para user_id=%d", user_id)
+        return
+
+    try:
+        idx = int(query.data or "0")
+        answer = options[idx]["label"]
+    except (ValueError, IndexError):
+        answer = str(query.data or "")
+
+    future.set_result(answer)
+    logger.info("[callback_query] future resolvida para user_id=%d com answer=%r", user_id, answer)

matraca-0.1.0/app/channels/telegram/bot.py

@@ -0,0 +1,105 @@
+import asyncio
+import logging
+from contextlib import suppress
+
+from pydantic_ai import Agent
+from telegram import Update
+from telegram.ext import Application, CallbackQueryHandler, ContextTypes, TypeHandler
+
+from app.channels.telegram.ask_user import handle_callback_query
+from app.channels.telegram.handlers import (
+    create_message_handler,
+    create_start_command_handler,
+)
+from app.deps import MatracaDeps
+from app.history import HistoryManager
+from app.setup import ContactsData, MatracaConfig, MatracaSetup
+from app.watcher import ConfigWatcher
+
+logger = logging.getLogger(__name__)
+
+
+def run_telegram(
+    agent: Agent[MatracaDeps, str],
+    config: MatracaConfig,
+    setup: MatracaSetup,
+) -> bool:
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s"
+    )
+    history_manager = HistoryManager()
+
+    def _load_allowed_user_ids() -> set[int]:
+        try:
+            contacts = ContactsData.model_validate_json(
+                setup.paths.contacts_path.read_text(encoding="utf-8")
+            )
+            return {int(k) for k, v in contacts.telegram.items() if k.isdigit() and v.authorized}
+        except (FileNotFoundError, ValueError):
+            return set()
+
+    allowed_user_ids: set[int] = _load_allowed_user_ids()
+
+    async def _run() -> bool:
+        application = (
+            Application.builder()
+            .token(config.channels.telegram_bot_token)
+            .concurrent_updates(True)
+            .build()
+        )
+
+        start_command_handler = create_start_command_handler(setup=setup)
+        message_handler = create_message_handler(
+            agent=agent,
+            allowed_user_ids=allowed_user_ids,
+            config=config,
+            setup=setup,
+            history_manager=history_manager,
+        )
+
+        async def _log_all_updates(
+            update: Update, context: ContextTypes.DEFAULT_TYPE
+        ) -> None:
+            _ = context
+            logger.info("[ALL_UPDATES] %s", update)
+
+        application.add_handler(TypeHandler(Update, _log_all_updates), group=-1)
+        application.add_handler(start_command_handler)
+        application.add_handler(message_handler)
+        application.add_handler(CallbackQueryHandler(handle_callback_query))
+
+        await application.initialize()
+        await application.start()
+
+        async def _reload_contacts() -> None:
+            new_ids = _load_allowed_user_ids()
+            allowed_user_ids.clear()
+            allowed_user_ids.update(new_ids)
+            logger.info("Contacts reloaded: %d authorized user(s)", len(allowed_user_ids))
+
+        watcher = ConfigWatcher(setup.paths.config_path)
+        contacts_watcher = ConfigWatcher(setup.paths.contacts_path)
+        watch_task = asyncio.create_task(watcher.watch())
+        contacts_task = asyncio.create_task(contacts_watcher.watch(on_change=_reload_contacts))
+        try:
+            logger.info("Bot started and polling for messages")
+            if application.updater is not None:
+                _ = await application.updater.start_polling(
+                    allowed_updates=list(Update.ALL_TYPES)
+                )
+            _ = await watcher.changed.wait()
+        finally:
+            _ = watch_task.cancel()
+            _ = contacts_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await watch_task
+            with suppress(asyncio.CancelledError):
+                await contacts_task
+            if application.updater is not None:
+                await application.updater.stop()
+            _ = await application.stop()
+            await application.shutdown()
+
+        return watcher.changed.is_set()
+
+    return asyncio.run(_run())

matraca-0.1.0/app/channels/telegram/formatting.py

@@ -0,0 +1,72 @@
+import html
+import re
+
+
+def split_for_telegram(message: str, max_size: int = 4000) -> list[str]:
+    if len(message) <= max_size:
+        return [message]
+
+    chunks: list[str] = []
+    pending_content = message
+    while pending_content:
+        if len(pending_content) <= max_size:
+            chunks.append(pending_content)
+            break
+        candidate_chunk = pending_content[:max_size]
+        split_position = candidate_chunk.rfind("\n")
+        if split_position < 0:
+            split_position = candidate_chunk.rfind(" ")
+        if split_position < 0:
+            split_position = max_size
+        chunks.append(pending_content[:split_position])
+        pending_content = pending_content[split_position:].lstrip()
+    return chunks
+
+
+def markdown_to_telegram_html(markdown_text: str) -> str:
+    if not markdown_text:
+        return ""
+
+    code_blocks: list[str] = []
+    inline_codes: list[str] = []
+
+    def capture_code_block(match: re.Match[str]) -> str:
+        code_blocks.append(match.group(1))
+        return f"\x00CB{len(code_blocks) - 1}\x00"
+
+    def capture_inline_code(match: re.Match[str]) -> str:
+        inline_codes.append(match.group(1))
+        return f"\x00IC{len(inline_codes) - 1}\x00"
+
+    telegram_text = re.sub(r"```[\w]*\n?([\s\S]*?)```", capture_code_block, markdown_text)
+    telegram_text = re.sub(r"`([^`]+)`", capture_inline_code, telegram_text)
+    telegram_text = re.sub(r"^#{1,6}\s+(.+)$", r"\1", telegram_text, flags=re.MULTILINE)
+    telegram_text = re.sub(r"^>\s*(.*)$", r"\1", telegram_text, flags=re.MULTILINE)
+    telegram_text = html.escape(telegram_text)
+    telegram_text = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r"<a href=\"\2\">\1</a>", telegram_text)
+    telegram_text = re.sub(r"\*\*(.+?)\*\*", r"<b>\1</b>", telegram_text)
+    telegram_text = re.sub(r"__(.+?)__", r"<b>\1</b>", telegram_text)
+    telegram_text = re.sub(
+        r"(?<![A-Za-z0-9])_([^_]+)_(?![A-Za-z0-9])",
+        r"<i>\1</i>",
+        telegram_text,
+    )
+    telegram_text = re.sub(r"~~(.+?)~~", r"<s>\1</s>", telegram_text)
+    telegram_text = re.sub(r"^[-*]\s+", "• ", telegram_text, flags=re.MULTILINE)
+
+    for index, code_content in enumerate(inline_codes):
+        telegram_text = telegram_text.replace(
+            f"\x00IC{index}\x00", f"<code>{html.escape(code_content)}</code>"
+        )
+
+    for index, code_content in enumerate(code_blocks):
+        telegram_text = telegram_text.replace(
+            f"\x00CB{index}\x00", f"<pre><code>{html.escape(code_content)}</code></pre>"
+        )
+
+    return telegram_text
+
+
+def normalize_newlines(text: str) -> str:
+    normalized = text.replace("\\r\\n", "\n").replace("\\r", "\n")
+    return re.sub(r"\r\n?", "\n", normalized)