Portable Autonomous AI Agent (GUI)

English README

"Created by a SysAdmin for developers. Focus on safety, portability, and zero-nonsense execution. No Docker, no heavy environments, just one binary."

Десктопный AI-агент с runtime на LangGraph и графическим интерфейсом на PySide6.
Работает с файлами, shell-командами, процессами, MCP-серверами и веб-поиском.

Запуск из исходников: python main.py
Сборка в portable .exe для Windows: build.bat

Цель проекта

Это не AI IDE. Цель — предоставить переносимого автономного помощника, которого можно скопировать на другой компьютер и сразу использовать с минимальной настройкой.

Основные приоритеты:

• переносимость;
• безопасность;
• локальные инструменты;
• автоматизация;
• работа с файлами и локальными процессами;
• поиск информации в интернете;
• надёжность.

Проект не стремится конкурировать с AI IDE по количеству функций и не пытается заменить специализированные инструменты для разработки. Фокус — практическое выполнение повседневных задач: работа с файлами, shell-командами, локальными процессами, веб-поиском, документацией, скриптами и автоматизацией в одном переносимом приложении без сложной инфраструктуры и дополнительных сервисов.

Возможности

• Графовый runtime на LangGraph с bounded recovery и self-correction
• Mixed-mode parallel tool batch: read-only инструменты запускаются параллельно через asyncio.gather, остальные — последовательно; результаты собираются в исходном порядке
• GUI: история чатов, streaming transcript, tool cards, approvals, user-choice карточки, вложения
• Fuzzy replay suppression: повторный префейс модели после tool-вызова подавляется даже при минимальных расхождениях текста (опечатки, пунктуация)
• Live CLI output streaming: вывод shell-команд отображается в карточке инструмента в реальном времени, а не только после завершения
• Exit-code-neutral команды: grep, rg, vulture, pytest, diff и др. с ненулевым exit code не помечаются как ошибка — вывод возвращается с префиксом Exit Code: N
• Stream-interruption recovery с классификацией ошибок (rate_limit / timeout / server_error / network) и экспоненциальным backoff с джиттером перед авто-продолжением
• Инструменты: filesystem (включая download_file), shell, Tavily web search/fetch, process management, MCP
• Approval-паузы перед мутирующими и деструктивными действиями
• Автосуммаризация контекста при длинных сессиях
• Настраиваемые HTTP-заголовки для OpenAI-compatible и Anthropic LLM через headers.json (эмуляция совместимых клиентов и прокси)
• Несколько профилей моделей с переключением прямо в GUI
• Durable checkpoints — сессии сохраняются между запусками
• Опциональный image input, если модель его поддерживает

Быстрый старт

Требования: Python 3.10+, API-ключ Gemini, OpenAI или Anthropic. Web search/fetch — опционально: для них нужны пакет tavily-python из requirements.txt и TAVILY_API_KEY в .env.

python -m venv venv
venv\Scripts\pip.exe install -r requirements.txt
Copy-Item env_example.txt .env
# Открой .env и укажи API-ключ выбранного LLM-провайдера
# Для Tavily-поиска также укажи TAVILY_API_KEY
python main.py

Для Claude Sonnet 5 и Opus 4.6+ задавайте ANTHROPIC_REASONING=adaptive; ANTHROPIC_THINKING_BUDGET предназначен для старых моделей. Полный список параметров находится в документации конфигурации.

Portable сборка

.\build.bat

Использует PyInstaller в режиме --onefile --windowed. Результат — один .exe без зависимостей.

Архитектура

START
  → summarize        # сжать контекст если сессия стала большой
  → update_step
  → agent            # LLM решает: ответить / вызвать tool / recovery
     → approval      # пауза перед мутирующим действием
        → tools
     → tools         # исполнить tool calls (read-only — параллельно, остальные — последовательно)
        → recovery   # если tool вернул ошибку
        → update_step
     → recovery      # если агент вернул protocol error или loop
        → update_step
        → END
     → END

Подробнее: Runtime Flow, Prompt Layers, Sessions & Checkpoints

Структура проекта

.
├── main.py                # Точка входа GUI
├── agent.py               # Сборка графа LangGraph: routing, tool binding, checkpointing
├── prompt.txt             # Основной системный промпт
├── mcp.json               # Конфигурация MCP-серверов
├── env_example.txt        # Шаблон .env
├── provider_registry.json # Reasoning kwargs для OpenAI-compatible провайдеров
├── build.bat              # Сборка portable .exe
├── requirements.txt
├── core/                  # Ядро агента: config, state, policies, recovery, provider registry
│   ├── nodes/             # Узлы LangGraph: context, llm, agent, tools, approval, recovery
│   └── providers/         # Provider-адаптеры (Anthropic, Gemini, OpenAI-compatible)
├── tools/                 # Filesystem/download, shell, search, process, user input, MCP registry
├── ui/                    # PySide6 GUI, runtime worker, streaming/status handling
├── docs/                  # Документация
├── tests/                 # Runtime, UI, tools, provider registry, logging, policies
├── .agent_state/          # Локальное состояние, профили, checkpoints
└── logs/                  # JSONL/runtime/debug logs

Полная карта модулей: docs/PROJECT_STRUCTURE.md

Тесты

Запустите полный regression-набор:

venv\Scripts\python.exe -m pytest

Зависимости

ripgrep (rg) — рекомендуется

Для более эффективного поиска по файлам, логам, конфигурациям и кодовым базам рекомендуется установить ripgrep. Готовые сборки для Windows — в Releases (архив x86_64-pc-windows-msvc.zip).

Для portable-сборки скопируйте rg.exe рядом с исполняемым файлом агента. Если rg отсутствует, агент продолжит работать в обычном режиме, используя стандартные инструменты файловой системы.

Python-пакеты

Документация