aisha 0.2.2__tar.gz

aisha-0.2.2/.gitattributes

@@ -0,0 +1 @@
+*.py linguist-language=Pyhton

aisha-0.2.2/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+*.log

aisha-0.2.2/.opencode/memory/.gitignore

@@ -0,0 +1 @@
+*

aisha-0.2.2/.opencode/memory/project.md

@@ -0,0 +1,7 @@
+---
+description: ''
+label: project
+limit: 5000
+read_only: false
+---
+

aisha-0.2.2/INSTALL.md

@@ -0,0 +1,246 @@
+# Установка агента aisha
+
+`aisha` — локальный консольный AI-агент на Python 3.11+. Он работает с внешним `llama-server` (llama.cpp) через OpenAI-совместимый API и не требует облачных LLM или API-ключей.
+
+## 1. Требования
+
+- **OS:** Windows 11 (основная), также работает на других ОС, поддерживающих Python 3.11+
+- **Python 3.11+** (включая `pip` и `venv`)
+- **Запущенный `llama-server`** из llama.cpp с поддержкой OpenAI-compatible API
+- **GGUF-модель** и, при необходимости, chat-template (jinja)
+
+## 2. Установка Python (если ещё нет)
+
+Проверьте версию:
+
+```powershell
+python --version
+```
+
+Нужен `Python 3.11` или новее. Если Python отсутствует — установите его с https://www.python.org/downloads/ (обязательно отметьте «Add python.exe to PATH»).
+
+## 3. Установка aisha
+
+Склонируйте или скопируйте репозиторий в рабочую директорию, затем из корня проекта:
+
+### Вариант 1: в текущее окружение Python
+
+```bash
+pip install -e ".[dev]"
+```
+
+`-e` (editable) устанавливает агент в режиме разработки: изменения в `src/` сразу подхватываются, а команда `aisha` доступна глобально. Dev-зависимости (pytest, ruff) ставятся вместе.
+
+### Вариант 2: изолированно через pipx
+
+```bash
+pipx install .
+```
+
+Изолирует агент и его зависимости от остального окружения. Команда `aisha` также доступна глобально.
+
+> Примечание: зависимости проекта — `httpx`, `rich`, `prompt-toolkit`, `ddgs`, `beautifulsoup4`, `PyYAML`. Они ставятся автоматически.
+
+### Проверка установки
+
+```bash
+aisha --help
+```
+
+Должна отобразиться справка по команде.
+
+## 4. Установка и настройка llama-server
+
+`aisha` не загружает модель сам — за него это делает внешний `llama-server`.
+
+1. Скачайте сборку llama.cpp (CUDA или CPU) с https://github.com/ggml-org/llama.cpp/releases.
+2. Скачайте GGUF-модель, например Qwen:
+   `d:\models\llama\qwen\Qwen3.5-9B-UD-Q4_K_XL.gguf`
+3. При необходимости подготовьте jinja chat-template:
+   `d:\models\llama\qwen\chat_template.jinja`
+
+### Запуск сервера
+
+```powershell
+z:\llamacpp\cuda\llama-server.exe `
+  -m d:\models\llama\qwen\Qwen3.5-9B-UD-Q4_K_XL.gguf `
+  --no-mmproj `
+  --jinja `
+  --chat-template-file "d:\models\llama\qwen\chat_template.jinja" `
+  --tools all `
+  -c 65536 `
+  -fa on `
+  --fit off `
+  --load-mode mlock `
+  --host localhost `
+  --port 8088 `
+  -a Qwen3.5-9B-Q4_K_XL `
+  -ngl 99 `
+  -np 1 `
+  -t 8 `
+  -ctk q8_0 `
+  -ctv q8_0 `
+  -ub 1024 `
+  -lv 4
+```
+
+Ключевые параметры для работы с `aisha`:
+
+| Параметр | Значение | Назначение |
+| --- | --- | --- |
+| `--host localhost` | локальный доступ | безопаснее, чем `0.0.0.0` |
+| `--port 8088` | порт агента по умолчанию | совпадает с дефолтом в конфиге |
+| `--tools all` | tool calling | нативный OpenAI-style tool calling |
+| `-a Qwen3.5-9B-Q4_K_XL` | alias модели | только подсказка для агента |
+| `-c 65536` | контекст | должен совпадать с `context_window` в конфиге |
+
+> Безопасность: не публикуйте `llama-server` в интернет. Без reverse proxy, аутентификации и ограничения доступа он должен слушать только `localhost`.
+
+### Проверка сервера
+
+```powershell
+Invoke-RestMethod http://localhost:8088/health
+```
+
+Ожидаемый ответ:
+
+```text
+{"status":"ok"}
+```
+
+## 5. Конфигурация aisha
+
+Агент работает с настройками по умолчанию сразу после установки, но для удобства можно создать глобальный конфиг.
+
+### Глобальная конфигурация
+
+Файл: `%USERPROFILE%\.aisha\config.toml`
+
+```toml
+[server]
+base_url = "http://localhost:8088"
+model = "Qwen3.5-9B-Q4_K_XL"
+connect_timeout = 5
+request_timeout = 600
+
+[llm]
+temperature = 0.6
+max_output_tokens = 65536
+context_window = 65536
+context_soft_limit = 0.85
+max_tool_iterations = 25
+
+[tools]
+shell = true
+web_search = true
+permission = "ask"
+shell_type = "powershell"
+shell_timeout = 120
+max_output_chars = 65536
+allow_read_outside_workspace = false
+allow_write_outside_workspace = false
+
+[web]
+timeout = 20
+max_results = 8
+max_page_bytes = 2097152
+max_content_chars = 50000
+allow_private_hosts = false
+
+[memory]
+enabled = true
+max_block_chars = 30000
+
+[ui]
+theme = "dark"
+stream = true
+show_reasoning = false
+debug = false
+```
+
+> Имя модели в конфиге — только подсказка. Если объявленное имя не совпадает с `-a` на сервере, `aisha` автоматически подключается к первой доступной модели и не падает.
+
+### Проектная конфигурация
+
+Файл `<workspace>/aisha.toml` переопределяет глобальные настройки для конкретного проекта. Он **не может ослабить безопасность**: `permission = "auto"`, чтение/запись за пределами workspace и т.п. приводят к ошибке конфигурации.
+
+### Приоритет настроек
+
+1. Аргументы командной строки
+2. Переменные окружения (`AISHA_SERVER_URL`, `AISHA_MODEL`, `AISHA_PERMISSION`, `AISHA_SHELL`, `AISHA_CONTEXT_WINDOW`, `AISHA_MAX_OUTPUT_TOKENS`)
+3. Проектный `aisha.toml`
+4. Глобальный `~/.aisha/config.toml`
+5. Значения по умолчанию
+
+## 6. Диагностика
+
+Проверка соединения с сервером и доступности модели:
+
+```bash
+aisha --doctor
+```
+
+Расширенная проверка tool calling (отправляет безопасный тестовый запрос без shell-команд и записи файлов):
+
+```bash
+aisha --doctor --tool-call-test
+```
+
+## 7. Первый запуск
+
+Из любой рабочей директории:
+
+```bash
+aisha
+```
+
+Откроется интерактивный REPL. Полезные команды: `/status` — сервер, модель, workspace, токены; `/help` — справка.
+
+Одноразовый запрос:
+
+```bash
+aisha "Объясни структуру этого проекта"
+```
+
+Другие полезные флаги:
+
+```bash
+aisha --server http://localhost:8088   # другой llama-server
+aisha --model Qwen3.5-9B-Q4_K_XL       # переопределение модели
+aisha -r                               # режим только для чтения
+aisha --permission deny                # запрет shell-команд
+aisha --permission auto                # выполнять разрешённые команды без подтверждения
+aisha --shell cmd                      # cmd вместо PowerShell
+aisha --tools-only                     # список доступных инструментов
+```
+
+## 8. Обновление
+
+Обновите код из репозитория и переустановите пакет:
+
+```bash
+pip install -e ".[dev]" --upgrade
+```
+
+Для pipx:
+
+```bash
+pipx upgrade aisha
+```
+
+## 9. Устранение неполадок
+
+| Симптом | Решение |
+| --- | --- |
+| `ServerUnavailableError` при старте REPL | `llama-server` не запущен или недоступен. Проверьте `http://localhost:8088/health`. |
+| Модель ещё загружается | Подождите, пока `llama-server` не загрузит GGUF, затем повторите `aisha --doctor`. |
+| Ошибка конфигурации из `aisha.toml` | Проектный конфиг не может ослаблять безопасность — переместите такие настройки в глобальный `config.toml` или передайте флагом CLI. |
+| Команда `aisha` не найдена | Переустановите пакет (`pip install -e .`) или проверьте, что каталог Scripts Python в PATH. |
+| `permission = "ask"` мешает | Запустите с `--permission auto` или задайте `AISHA_PERMISSION=auto`. |
+
+## 10. Тестирование и проверка кода (разработка)
+
+```bash
+python -m pytest tests/ -q   # тесты (не требуют llama-server)
+ruff check src/ tests/       # линт
+```

aisha-0.2.2/LICENSE

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

aisha-0.2.2/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.5
+Name: aisha
+Version: 0.2.2
+Summary: Local console AI agent for working with source code, files, CLI and internet
+Project-URL: Homepage, https://github.com/cruide/aisha
+Project-URL: Website, https://alex-tisch.ru
+Author-email: Tischenko Alexander <info@alex-tisch.ru>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Russian
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: ddgs>=9.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aisha
+
+Локальный консольный AI-агент на Python 3.11+. Работает с внешним
+[llama-server](https://github.com/ggml-org/llama.cpp) (llama.cpp) по
+OpenAI-совместимому REST API. Это **не веб-приложение**: вся логика — цикл
+«запрос модели → вызовы инструментов → результаты → снова модель» в одном процессе.
+
+Версия: `0.2.2`.
+
+## Возможности
+
+- **Файлы** — чтение, запись, точечное редактирование, листинг, `glob`-поиск и `grep`;
+- **Shell** — запуск команд (`powershell`/`cmd`/`sh`), таймауты, обрезка вывода, подтверждение опасных команд;
+- **Веб** — поиск DuckDuckGo и загрузка страниц с SSRF-защитой;
+- **Память** — постоянные блоки (глобальные и проектные) с приоритетом проекта;
+- **Скиллы** — переиспользуемые инструкции в `SKILL.md`;
+- **Многошаговые задачи** — todo-список и уточняющие вопросы к пользователю;
+- **Нативный tool calling** — модель сама вызывает инструменты через API;
+- **Авто-сжатие истории** при приближении к лимиту контекста;
+- **Два режима** — one-shot (передан промпт) и интерактивный REPL.
+
+## Требования
+
+- Python **3.11+**;
+- запущенный **llama-server** (llama.cpp) с поддержкой OpenAI-совместимого API и tool calling.
+
+## Установка
+
+```bash
+pip install -e ".[dev]"   # src-layout: без этого пакет `aisha` не импортируется
+```
+
+Точка входа — `aisha = "aisha.cli:main"` (см. `pyproject.toml`).
+
+## Запуск llama-server
+
+Перед использованием нужно поднять сервер, например:
+
+```bash
+llama-server \
+  --model ./models/Qwen3.5-9B-Q4_K_XL.gguf \
+  --port 8088 \
+  --n-gpu-layers 99
+```
+
+По умолчанию aisha ждёт сервер на `http://localhost:8088`. Проверить подключение:
+
+```bash
+aisha --doctor
+```
+
+## Быстрый старт
+
+```bash
+aisha "объясни, что делает этот проект"   # one-shot: один запрос и выход
+aisha                                       # без аргументов — интерактивный REPL
+python -m aisha ...                         # эквивалентный вызов
+```
+
+## CLI
+
+```
+aisha [промпт...] [флаги]
+```
+
+| Флаг | Описание |
+|---|---|
+| `prompt` (позиционный) | запрос; без него запускается REPL |
+| `--server URL` | адрес llama-server (по умолч. `http://localhost:8088`) |
+| `--model NAME` | имя модели на сервере |
+| `--api-key KEY` | API-ключ для сервера (если требуется авторизация) |
+| `-r`, `--read-only` | режим только для чтения (только безопасные инструменты) |
+| `--permission auto\|ask\|deny` | режим запуска shell-команд |
+| `--shell powershell\|cmd` | оболочка по умолчанию |
+| `--tools-only` | показать список инструментов и выйти |
+| `--doctor` | диагностика подключения к серверу |
+| `--tool-call-test` | вместе с `--doctor`: проверить tool calling |
+| `--no-color` | отключить цвета |
+| `--debug` | режим отладки: reasoning модели, дампы запросов/ответов, traceback |
+| `--version` | показать версию |
+
+## Конфигурация
+
+Приоритет (каждый слой глубоко сливается с предыдущим):
+
+```
+DEFAULTS  ←  ~/.aisha/config.toml  ←  <workspace>/aisha.toml  ←  env AISHA_*  ←  CLI-флаги
+```
+
+Полный пример `~/.aisha/config.toml`:
+
+```toml
+[server]
+base_url = "http://localhost:8088"
+model = "Qwen3.5-9B-Q4_K_XL"
+api_key = ""                  # необязательно; если сервер требует авторизацию (Bearer)
+connect_timeout = 5.0
+request_timeout = 600.0
+
+[llm]
+temperature = 0.6
+top_p = 0.9                 # необязательно; None = не передавать (используется серверный умолчание)
+top_k = 40                  # необязательно; целое > 0
+repeat_penalty = 1.1        # необязательно; > 0
+frequency_penalty = 0.0     # необязательно; -2.0 .. 2.0
+max_output_tokens = 32768
+context_window = 32768
+context_soft_limit = 0.85
+max_tool_iterations = 25
+tool_guide = false           # true — добавить «Справочник инструментов» в системный промпт (для слабых моделей)
+
+[tools]
+shell = true
+web_search = true
+permission = "ask"          # auto | ask | deny
+shell_type = "powershell"
+shell_timeout = 120
+max_output_chars = 65536
+allow_read_outside_workspace = false
+allow_write_outside_workspace = false
+
+[web]
+timeout = 20
+max_results = 8
+max_page_bytes = 2097152
+max_content_chars = 50000
+allow_private_hosts = false
+
+[memory]
+enabled = true
+max_block_chars = 30000
+
+[ui]
+theme = "dark"
+stream = true
+show_reasoning = false
+debug = false                 # true — то же, что --debug: reasoning + дампы запросов/ответов
+input_history = "~/.aisha/input_history.txt"
+```
+
+Переменные окружения:
+
+| Переменная | Куда |
+|---|---|
+| `AISHA_SERVER_URL` | `server.base_url` |
+| `AISHA_MODEL` | `server.model` |
+| `AISHA_API_KEY` | `server.api_key` |
+| `AISHA_PERMISSION` | `tools.permission` |
+| `AISHA_SHELL` | `tools.shell_type` |
+| `AISHA_CONTEXT_WINDOW` | `llm.context_window` |
+| `AISHA_MAX_OUTPUT_TOKENS` | `llm.max_output_tokens` |
+
+Конфиг строго валидируется: неизвестная секция или ключ вызывает ошибку.
+**Проектный `aisha.toml` ограничен в правах безопасности** — он не может ставить
+`permission = "auto"`, включать доступ за пределы workspace или включать `shell`,
+если тот отключён глобально. Это защита от «троянского» конфига в склонированном репозитории.
+
+## Инструменты
+
+| Инструмент | Read-only | Назначение |
+|---|---|---|
+| `read_file` | да | чтение файла UTF-8 с offset/limit |
+| `write_file` | нет | создание/перезапись (атомарно) |
+| `edit_file` | нет | точная замена фрагмента текста |
+| `list_dir` | да | содержимое каталога |
+| `glob` | да | поиск файлов по маске |
+| `grep` | да | regex-поиск по содержимому |
+| `run_command` | нет | запуск shell-команды |
+| `web_search` | да | поиск DuckDuckGo |
+| `web_fetch` | да | загрузка веб-страницы |
+| `todowrite` | да | полная замена todo-списка сессии |
+| `ask_user` | да | уточняющий вопрос (только в REPL) |
+| `memory_list` / `memory_get` | да | список/чтение блоков памяти |
+| `memory_set` / `memory_replace` | нет | запись/правка блоков памяти |
+| `skill` | да | загрузить текст скилла по имени |
+
+Файловые инструменты не выходят за пределы workspace (path-traversal блокируется),
+если не включён соответствующий `allow_*_outside_workspace`.
+
+## Память и скиллы
+
+- **Память** — JSON-блоки в `~/.aisha/memory/` (глобально) и `<workspace>/.aisha/memory/`
+  (проектно). Проектный блок перекрывает глобальный с тем же `label`.
+  Вызов `memory_get` не выводится в консоль (это фоновое чтение собственной памяти агента).
+- **Скиллы** — каталоги `~/.aisha/skills/<name>/SKILL.md` и
+  `<workspace>/.aisha/skills/<name>/SKILL.md` с обязательным YAML-frontmatter
+  (`name`, `description`).
+
+## Кастомный системный промпт (SYSTEM.md)
+
+Если в корне проекта есть файл `<workspace>/.aisha/SYSTEM.md`, его содержимое
+**полностью заменяет** встроенный системный промпт aisha (persona, окружение, правила,
+секции памяти и скиллов). При этом «Справочник инструментов» (`tool_guide = true`),
+`AGENTS.md` и текущий todo-список по-прежнему добавляются после него. Файл обрезается
+до 64 КБ, как и `AGENTS.md`.
+
+## REPL
+
+Команды внутри интерактивного режима:
+
+| Команда | Действие |
+|---|---|
+| `/help` | справка |
+| `/new` | новая сессия (сброс истории) |
+| `/status` | сервер, модель, workspace, режим, токены |
+| `/tools` | список инструментов |
+| `/skills` | индекс скиллов |
+| `/memory` | блоки памяти |
+| `/compact` | принудительное сжатие истории |
+| `/doctor` | проверка соединения |
+| `/init` | изучить проект и создать `AGENTS.md` |
+| `/clear` | очистка экрана |
+| `/quit`, `/exit`, `Ctrl+D` | выход |
+
+Дополнительно: `Ctrl+C` отменяет текущий запрос (REPL не завершается),
+`Ctrl+↑/↓` — история запросов, `Tab` — автодополнение команд и путей.
+
+## Безопасность
+
+- Запуск shell-команд в режиме `permission = "ask"` требует подтверждения;
+  опасные команды (`rm -rf`, `Remove-Item -Recurse`, `git reset --hard` и т.п.)
+  подтверждаются всегда.
+- `web_fetch` блокирует private/localhost/loopback-адреса (SSRF-защита), если не
+  включён `web.allow_private_hosts`.
+- `find_danger` в `shell.py` — **эвристика по regex, а не песочница**: обойти её можно.
+  Не запускайте aisha от имени пользователя с повышенными правами в недоверенном окружении.
+
+## Разработка
+
+```bash
+pip install -e ".[dev]"
+
+pytest                        # весь набор; реальный сервер не нужен
+pytest tests/test_config.py   # один тест
+
+ruff check .                  # линт (E, F, I, W; line-length 100)
+```
+
+Тесты не ходят в реальный сервер: `test_client.py` подменяет транспорт
+`httpx.MockTransport`, конфиг-тесты подменяют `Path.home`.
+
+## Структура проекта
+
+```
+src/aisha/
+├── cli.py        # entry point: args → config → registry → client → AgentLoop → UI
+├── client.py     # async SSE-клиент к llama-server, ретраи, tool-call сборка
+├── agent.py      # AgentLoop: цикл модель↔инструменты, компакция
+├── context.py    # системный промпт, история, оценка токенов
+├── config.py     # конфигурация, валидация, безопасность
+├── memory.py     # постоянная память (блоки)
+├── skills.py     # скиллы (SKILL.md)
+├── ui.py         # ConsoleUI: rich + prompt_toolkit, REPL
+├── fsutil.py     # атомарная запись, проверка путей, human_size
+├── errors.py     # иерархия исключений
+└── tools/        # реализации инструментов (base, files, shell, web, extras)
+```
+
+Подробную картину по модулям, неочевидным решениям и «граблям» см. в
+[`PROJECT.md`](PROJECT.md).