██████╗ ██╗      █████╗ ██╗██╗
  ██╔════╝ ██║     ██╔══██╗██║██║
  ██║      ██║     ███████║██║██║
  ██║      ██║     ██╔══██║██║██║
  ╚██████╗ ███████╗██║  ██║██║██║
   ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝╚═╝   
   (CLAII)

CLAII – AI-агент для кодинга с приоритетом CLI

CLAII (произносится как «клей») — это AI-агент для кодинга с приоритетом командной строки, который может:

• Просматривать и перемещаться по файлам проекта
• Читать содержимое файлов
• Записывать / перезаписывать файлы
• Выполнять Python-код в изолированной рабочей директории
• Работать в цикле агента с использованием вызовов инструментов (function calling) до завершения задачи
• Использовать локальную базу знаний и лёгкую память для сохранения контекста

Он разработан как небольшое ядро, которое можно расширять дополнительными инструментами, провайдерами и поведением агента со временем.

✨ Возможности (текущие)

🧠 Агентный цикл

CLAII вызывает LLM в цикле, планируя вызовы инструментов шаг за шагом, пока не сможет дать окончательный ответ или завершит последовательность изменений/тестов.

📁 Инструменты файловой системы (с ограниченным доступом)

• get_files_info – список файлов и директорий с размером и флагом is_dir
• get_file_content – чтение содержимого файла с ограничением по максимальной длине (MAX_FILE_CHARS)
• write_file – запись/перезапись файлов (в пределах разрешённой рабочей директории)
• run_python_file – выполнение Python-скриптов с тайм-аутом и захватом вывода

🔐 Рабочая область с ограничениями безопасности

Все инструменты ограничены настроенной рабочей директорией (по умолчанию ./calculator), чтобы агент не выходил за её пределы.

📚 Интеграция с базой знаний и @упоминания

• Папка kb/ внутри рабочей директории
• @kb/<путь> – встраивание содержимого базы знаний напрямую в промпт
• @file:<путь> – подсказка CLAII просмотреть конкретный файл проекта через get_file_content

🧠 Лёгкая память (опционально)

• Сохраняет сжатую историю диалога в .claii_memory.json для каждого проекта
• Может быть отключена с помощью --no-memory
• Обрезка истории может быть отключена через --no-prune

🧮 Демонстрационный проект «Калькулятор»

Небольшое приложение-калькулятор (calculator/), которое CLAII может читать, изменять и запускать — используется как тестовая площадка для автоматического исправления ошибок и рефакторинга.

🖥️ Точка входа через CLI + ASCII-лого

Запустите claii "ваш запрос здесь" и получите приветственное сообщение с баннером CLAII перед запуском агента.

🧭 Дорожная карта / Планируемые возможности

Направления развития расширенной версии AgencySwarm / CLAII:

🔀 Подключаемые провайдеры ИИ и модели

Поддержка нескольких бэкендов (например, Google Gemini, OpenAI, Anthropic, локальные LLM) через простой переключатель в конфигурации/CLI с унифицированным интерфейсом вызова инструментов для агента.

🧠 Расширенная память проекта

• Хранение резюме, решений и архитектурных заметок для каждого проекта
• Команды для явного просмотра/обрезки/очистки памяти

🧰 Расширяемые инструменты и интеграция с MCP

• Регистрация новых инструментов (например, Neo4j через MCP, HTTP API, операции с git)
• Автоматическая регистрация через простую конвенцию functions/ и объявления схем

🕸️ Рои мультиагентов и параллельные рабочие процессы

• Специализированные агенты: исправитель ошибок, рефакторингщик, автор документации, тестировщик и т. д.
• Параллельные операции с разными файлами/директориями с координационным слоем

📚 Углублённые рабочие процессы с базой знаний

• Планирование с учётом базы знаний («прочитать проектную документацию, затем провести рефакторинг»)
• Структурированные резюме базы знаний и поиск на основе эмбеддингов

🎨 Улучшенный UX в CLI

• Цветовое кодирование ввода/вывода и трассировки инструментов
• Опциональные предпросмотры изменений в виде diff при модификации файлов
• «Тихий» и «отладочный» режимы для разных уровней детализации

🧱 Обзор архитектуры

Текущая высокоуровневая структура:

claii/
  __init__.py
  cli.py          # CLI entrypoint (prints logo, parses args, calls run_agent)
  agent.py        # Core agent loop + function dispatch + memory + @mentions
  memory.py       # Load/save compressed conversation history
  config.py       # Provider config (CLAII_PROVIDER, CLAII_MODEL)
  providers.py    # GeminiProvider and future multi-provider abstractions

functions/
  __init__.py
  config.py             # e.g. MAX_FILE_CHARS / function-level config
  get_files_info.py     # get_files_info(...) + schema_get_files_info
  get_file_content.py   # get_file_content(...) + schema_get_file_content
  write_file.py         # write_file(...) + schema_write_file
  run_python.py         # run_python_file(...) + schema_run_python_file
  get_kb_file.py        # get_kb_file(...) + schema_get_kb_file

calculator/
  __init__.py
  main.py         # Calculator CLI app (demo project)
  tests.py        # Unit tests for calculator
  main.txt        # Example text file
  README.md
  pkg/
    __init__.py
    calculator.py
    render.py
    morelorem.txt

pyproject.toml
README.md
.env.example        # Example environment file (optional)
.claii_memory.json  # Created at runtime (per-project memory)

🧠 Поведение агента и системный промпт

На высоком уровне агент получает инструкции следующего содержания:

Возможности

• Перечислять файлы и директории
• Читать содержимое файлов
• Выполнять Python-файлы с опциональными аргументами
• Записывать или перезаписывать файлы

Всегда должен

• Использовать пути относительно рабочей директории
• Применять инструменты вместо угадывания содержимого файлов
• Составлять план перед внесением изменений
• Проверять изменения запуском тестов, если они доступны

Рабочий процесс рефакторинга / исправления ошибок

1. Использовать get_files_info для обнаружения релевантных файлов
2. Использовать get_file_content для изучения кода
3. Описать краткий план на естественном языке
4. Применить целенаправленные изменения с помощью write_file
5. Использовать run_python_file для запуска тестов или скриптов с целью проверки

Использование базы знаний

• @kb/<путь> → рассматривается как ссылка на kb/<путь> внутри рабочей директории
• @file:<путь> → рассматривается как подсказка просмотреть этот файл проекта через get_file_content

Цикл агента продолжает вызывать метод generate(...) провайдера, пока:

• Больше не требуется вызовов инструментов, и
• Модель не вернёт непустой окончательный текст.

📦 Установка

Требуется Python 3.11+.

# Clone the repo
git clone git@github.com:agencyswarm/CLAII.git
cd CLAII

# Create & activate a virtualenv (recommended)
python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scripts?ctivate

# Install in editable/dev mode
pip install -e .

# Run once to verify the CLI is installed
claii --help  # (future: help text; for now, just try a prompt)

Зависимости

Основные зависимости (указаны в pyproject.toml):

• google-genai – клиент Gemini API
• python-dotenv – загрузка GEMINI_API_KEY и других переменных окружения

🔧 Конфигурация

Создайте файл .env в корне проекта с как минимум:

GEMINI_API_KEY=your_gemini_api_key_here

Текущая абстракция провайдера находится в claii/providers.py:

• GeminiProvider оборачивает google-genai и обрабатывает:
  • Загрузку API-ключа (dotenv)
  • Выбор модели (gemini-2.0-flash-001 по умолчанию)

Дополнительная конфигурация (уже подготовлена в claii/config.py):

CLAII_PROVIDER=google-genai
CLAII_MODEL=gemini-2.0-flash-001

На данный момент get_provider() просто возвращает GeminiProvider, но класс конфигурации уже готов для добавления других провайдеров.

🚀 Использование

После установки (и активации виртуального окружения):

1. Базовый вызов

claii "explain how the calculator works"

Вы должны увидеть:

• ASCII-логотип CLAII
• Строки вызова инструментов (например, Calling function: get_files_info({...}))
• Итоговое объяснение

2. Флаги

Текущий CLI настроен следующим образом:

claii "<prompt>" [--verbose] [--no-memory] [--no-prune]

• --verbose Выводит аргументы вызова инструментов и их сырые результаты (полезно для отладки).

• --no-memory Отключает загрузку/сохранение .claii_memory.json для текущего проекта. Агент работает только с текущим запросом и шагами в рамках этого запуска.

• --no-prune Отключает обрезку истории сообщений перед сохранением. По умолчанию сохраняются только последние MAX_MEMORY_MESSAGES (например, 200).

Примеры

# Normal run, memory enabled and pruned
claii "fix the bug where 3 + 7 * 2 returns 20 instead of 17"

# Debug everything, but do not persist history
claii "run the calculator tests" --verbose --no-memory

# Long-running debugging session, keep full history
claii "help me refactor calculator/pkg/calculator.py" --no-prune

3. База знаний и упоминания @

В рабочей директории (по умолчанию calculator/) можно создать:

calculator/
  kb/
    design.md
    architecture/decisions.md
    lang/agent-architecture.md

Используйте их в запросах следующим образом:

# Inline KB context from kb/design.md
claii "Using @kb/design.md, refactor the calculator to follow the design guidelines."

# Hint to a specific project file
claii "Based on @kb/lang/agent-architecture.md, review @file:calculator/pkg/calculator.py and suggest improvements."

Поведение

• @kb/<путь>
  • Соответствует шаблону KB_PATTERN = r"@kb/([^\s]+)"

  • CLAII разворачивает его в встроенный текст:

    text Ниже содержимое файла базы знаний "kb/<путь>": --- НАЧАЛО БЗ [<путь>] --- ... содержимое файла (обрезается, если очень длинное) ... --- КОНЕЦ БЗ [<путь>] ---

• @file:<путь>
  • Соответствует шаблону FILE_PATTERN = r"@file:([^\s]+)"

  • CLAII не загружает файл автоматически, а переписывает его как подсказку:

    text "<путь>" (ссылка на файл проекта; используйте get_file_content с file_path="<путь>")

Другие использования @ (электронные адреса, соцсети, обычный текст) не затрагиваются, так как распознаются только эти конкретные шаблоны.

4. Примеры запросов

Показать содержимое директории:

claii "what files are in the root of the calculator project?" --verbose

Прочитать файл:

claii "read the contents of calculator/main.py"

Записать файл (в рабочей директории):

claii "create a new file calculator/notes.txt summarising what the calculator does"

Запустить тесты:

claii "run the calculator tests in calculator/tests.py"

Классическая демонстрация исправления ошибки:

claii "fix the bug where '3 + 7 * 2' evaluates to 20 instead of 17 in the calculator"

🧠 Модель памяти

Память реализована в claii/memory.py как простой JSON-лог:

• Файл: .claii_memory.json в корне проекта
• Схема: список записей вида { "role": "...", "text": "..." }
• Сохраняются только роль и объединённые части текста для компактности

При запуске:

Если память включена (по умолчанию), CLAII вызывает:

messages = load_memory(project_root)

Затем добавляет текущий (возможно, расширенный) запрос пользователя:

messages.append(
    types.Content(role="user", parts=[types.Part(text=expanded_prompt)])
)

При завершении:

Если память включена, опционально обрезает сообщения с помощью _prune_messages, а затем:

save_memory(project_root, messages)

Память можно отключить для запуска с помощью --no-memory или запретить обрезку с помощью --no-prune.

🔌 Провайдеры

Абстракция провайдера находится в claii/providers.py:

class GeminiProvider:
    def __init__(self, model_name: str = "gemini-2.0-flash-001") -> None:
        load_dotenv()
        api_key = os.getenv("GEMINI_API_KEY")
        ...
        self.client = genai.Client(api_key=api_key)
        self.model_name = model_name

    def generate(self, *, messages, tools, system_prompt):
        return self.client.models.generate_content(
            model=self.model_name,
            contents=messages,
            config=types.GenerateContentConfig(
                tools=tools,
                system_instruction=system_prompt,
            ),
        )

Агент вызывает только:

provider = get_provider()
response = provider.generate(
    messages=messages,
    tools=[tools],
    system_prompt=system_prompt,
)

Возможные дополнения:

• OpenAIProvider
• AnthropicProvider
• LocalProvider (например, vLLM, LM Studio и т. д.)

Каждому достаточно реализовать ту же сигнатуру generate(...).

🧩 Расширение CLAII

Некоторые направления для развития проекта:

1. Дополнительные инструменты

Добавьте модули в functions/ и зарегистрируйте их в agent.py:

• functions/git_tools.py
• functions/http_request.py
• functions/test_runner.py

Каждый должен экспортировать:

• your_tool(...) – чистая Python-функция с входными/выходными данными в виде строк
• schema_your_tool – types.FunctionDeclaration, описывающая параметры

Затем включите их в:

• _build_tools() – добавьте в function_declarations=[...]
• _call_function() – расширьте fn_map = { ... }

2. Оркестрация нескольких агентов

Создайте контроллер более высокого уровня, который:

• Запускает несколько вызовов run_agent с разными системными подсказками/ролями
• Использует общий файл памяти или передаёт резюме между агентами

Идеи оркестрации:

• Планировщик → Исполнитель → Тестировщик → Рецензент
• Конвейеры длительных рефакторингов

3. Улучшенный UX

- Цветной вывод с помощью rich или colorama

• Добавлен флаг --diff, который выводит минимальные различия при изменении файла с помощью write_file
• Добавлен режим --plan-only, в котором агент только проверяет и предлагает план без записи файлов

📝 Лицензия

Авторские права (C) Swarmic LLC. Все права защищены.