{"id":49352026,"url":"https://github.com/lifestreamy/local-lua-agent","last_synced_at":"2026-04-27T10:32:37.616Z","repository":{"id":353023520,"uuid":"1208661501","full_name":"lifestreamy/local-lua-agent","owner":"lifestreamy","description":"Fully local agentic system with prompt guarding \u0026 Lua code gen/validation via any Ollama-hosted model. Uses REST \u0026 SSE for async events. Built for True Tech Hack 2026 by OpenTeam2026 (Tim K. - Lead).","archived":false,"fork":false,"pushed_at":"2026-04-22T05:18:35.000Z","size":1116,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T07:21:37.008Z","etag":null,"topics":["ai-agent","code-generation","docker","fastapi","fullstack","hackathon","interactive-cli","llm","local-llm","lua","multi-agent","nextjs","ollama","prompt-engineering","prompt-guard","python","rest-api","server-sent-events","uvicorn","web-ui"],"latest_commit_sha":null,"homepage":"https://truetecharena.ru/contests/true-tech-hack2026","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lifestreamy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T15:31:12.000Z","updated_at":"2026-04-22T05:09:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lifestreamy/local-lua-agent","commit_stats":null,"previous_names":["lifestreamy/local-lua-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/lifestreamy/local-lua-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lifestreamy%2Flocal-lua-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lifestreamy%2Flocal-lua-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lifestreamy%2Flocal-lua-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lifestreamy%2Flocal-lua-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lifestreamy","download_url":"https://codeload.github.com/lifestreamy/local-lua-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lifestreamy%2Flocal-lua-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32333196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","code-generation","docker","fastapi","fullstack","hackathon","interactive-cli","llm","local-llm","lua","multi-agent","nextjs","ollama","prompt-engineering","prompt-guard","python","rest-api","server-sent-events","uvicorn","web-ui"],"created_at":"2026-04-27T10:32:36.057Z","updated_at":"2026-04-27T10:32:37.593Z","avatar_url":"https://github.com/lifestreamy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LocalScript\n\n## Содержание\n\n1. [Заголовок и краткое описание](#readme-1)\n2. [Быстрый запуск](#readme-2)\n3. [Структура проекта](#readme-3)\n4. [Клиенты](#readme-4)\n5. [API (асинхронная модель)](#readme-5)\n6. [Архитектурные контракты](#readme-6)\n7. [Ручной запуск (Ollama + uvicorn, без Docker)](#readme-7)\n\n\u003ca id=\"readme-1\"\u003e\u003c/a\u003e\n## 1. Заголовок и краткое описание\n\n**True Tech Hack 2026** · локальный ИИ-ассистент для генерации и проверки Lua-скриптов под **MWS Octapi LowCode**. Модель **Qwen2.5-Coder 7B** (Ollama) формирует код; целевая среда исполнения — **Lua 5.5** на стороне MWS; на стороне сервиса синтаксис проверяется компилятором **`luac`**. Обмен с клиентами — **асинхронно** (`task_id` + **SSE**). Облачные LLM API не используются.\n\n**Документация FastAPI (Swagger/OpenAPI):** после запуска сервиса открой `http://localhost:8080/docs` в браузере (интерактивное тестирование эндпоинтов) или `http://localhost:8080/openapi.json` (машиночитаемое описание API). Это одинаково работает и для ручного запуска `uvicorn`, и для запуска через `docker-compose`/`docker compose`, если API опубликован на `localhost:8080`.\n\n**Стек:** FastAPI (Python 3.11), Server-Sent Events, Docker, **`luac`**, **Rich** + **prompt_toolkit** (CLI), Next.js (Web UI).\n\n**Диаграммы C1–C3 (Mermaid):** [docs/архитектура_С4_визуал.md](docs/архитектура_С4_визуал.md) · **C4 (описание):** [docs/архитектура_С4-описание.md](docs/архитектура_С4-описание.md)\n\n---\n\n\u003ca id=\"readme-2\"\u003e\u003c/a\u003e\n## 2. **Быстрый запуск**\n\n**Выберите профиль железа и выполните одну команду из корня репозитория.**\n\n**Для стендов жюри с аппаратным ускорением (NVIDIA GPU)** — после установки [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html):\n\n```bash\ndocker-compose -f docker-compose-nvidia-gpu.yml up --build -d\n```\n\n**Для обычных систем (CPU fallback)** — без GPU passthrough в compose:\n\n```bash\ndocker-compose up --build -d\n```\n\nПосле старта: API — `http://localhost:8080`, Ollama — `http://localhost:11434`. Первый запуск может занять время (сборка образа, загрузка весов модели).\n\n---\n\n\u003ca id=\"readme-3\"\u003e\u003c/a\u003e\n## 3. Структура проекта\n\n| Путь | Назначение |\n|------|------------|\n| `api/` | FastAPI: маршруты, оркестрация задач, **Guard**, **Agent**, **LuaValidator**, SSE |\n| `cli-client/` | Интерактивный терминальный клиент (**Rich**, история ввода) |\n| `web-ui/` | Веб-интерфейс (Next.js), чат, подключение к API и SSE |\n| `prompts/` | Системные промпты генератора и guard |\n| `docs/` | Контракты API, контекста, отладка, архитектура C4 |\n| `tests/` | Автотесты и сценарии проверки |\n| `docker-compose.yml` / `docker-compose-nvidia-gpu.yml` | Обычный и GPU-вариант стека |\n\n---\n\n\u003ca id=\"readme-4\"\u003e\u003c/a\u003e\n## 4. Клиенты\n\n### CLI (интерактивный терминал)\n\nИз корня репозитория (Python 3.11+, venv по желанию):\n\n```bash\npip install -r requirements.txt\npython cli-client/chat.py\n```\n\nКлиент на **Rich** и **prompt_toolkit**: история запросов **стрелками вверх/вниз**, ответы модели и код — с **подсветкой** (Markdown-блоки `lua` в панелях Rich). Базовый URL API по умолчанию: `http://localhost:8080`.\n\n### Web UI\n\n```bash\ncd web-ui\nnpm install\nnpm run dev\n```\n\nОткройте `http://localhost:3000`. При необходимости задайте `NEXT_PUBLIC_API_BASE` (например `http://localhost:8080`).\n\n---\n\n\u003ca id=\"readme-5\"\u003e\u003c/a\u003e\n## 5. API (асинхронная модель)\n\nЗапрос **не блокирует** поток до готового кода: сервер принимает задачу и возвращает идентификатор; клиент подписывается на поток статусов.\n\n| Метод | Описание |\n|--------|----------|\n| `POST /generate` | Тело: `{\"prompt\": \"...\", \"context\": \"...\"?}`. Ответ: `{\"task_id\": \"\u003cuuid\u003e\"}`. Задача ставится в очередь, пайплайн выполняется в фоне. |\n| `GET /status?task_id=\u003cuuid\u003e` | **SSE** (`text/event-stream`). В теле событий — JSON с полями вроде `stage`, `message`, `code`, `error`. Типичные стадии: `pending`, `generating`, `validating`, `retrying`, `done`, `error`. |\n| `GET /health` | Проверка готовности API и связи с Ollama/моделью. |\n\nПодробные примеры и поля — в [docs/api_contract_description.md](docs/api_contract_description.md).\n\n---\n\n\u003ca id=\"readme-6\"\u003e\u003c/a\u003e\n## 6. Архитектурные контракты\n\n- **Введение в проект с нуля:** [docs/ONBOARDING.md](docs/ONBOARDING.md).\n- **Формат поля `context` для мульти-туровых диалогов** (защита от poisoning и инъекций через историю): [docs/КЛИЕНТ_КОНТЕКСТ_КОНТРАКТ.md](docs/КЛИЕНТ_КОНТЕКСТ_КОНТРАКТ.md).\n- **HTTP-контракт и SSE:** [docs/api_contract_description.md](docs/api_contract_description.md).\n- **Security Guard:** отдельный проход по промпту/контексту (Ollama `/api/chat` + правила в `api/guard.py` и промпте guard); при срабатывании блокировки клиент получает завершение с маркером безопасности в коде.\n- **LuaValidator:** вызов системного **`luac`** к сгенерированному коду; при ошибке синтаксиса текст ошибки подмешивается в следующую попытку генерации (**до 3 раз**, `MAX_RETRIES`). Локально без `luac` можно выставить `DRY_RUN=true` (см. [docs/DEBUGGING.md](docs/DEBUGGING.md)).\n\nДиаграммы уровней C1–C3: [docs/архитектура_С4_визуал.md](docs/архитектура_С4_визуал.md). Уровень **C4 (описание)** — [docs/архитектура_С4-описание.md](docs/архитектура_С4-описание.md).\n\n---\n\n\u003ca id=\"readme-7\"\u003e\u003c/a\u003e\n## 7. Ручной запуск (Ollama + uvicorn, без Docker)\n\nСценарий для разработки: три и более терминалов из **корня репозитория**. Подробные команды, переменные окружения, таблица тестов и примеры для CLI/Web UI — в [docs/ONBOARDING.md §12](docs/ONBOARDING.md#12-ручной-локальный-запуск-ollama-модели-uvicorn-тесты-cli-web-ui); типичные сбои (прокси, PS 5.1, UTF-8) — в [docs/DEBUGGING.md §3](docs/DEBUGGING.md#3-сценарий-b-ручной-запуск-windows-без-docker).\n\n1. **Ollama** — в первом терминале: `OLLAMA_KEEP_ALIVE=-1` (или в PowerShell `$env:OLLAMA_KEEP_ALIVE = \"-1\"`), затем **`ollama serve`**. Во втором терминале один раз: **`ollama pull qwen2.5-coder:7b-instruct-q4_K_M`** (или легче **`ollama pull qwen2.5-coder:0.5b`**). Имя модели должно совпасть с **`OLLAMA_MODEL`** у API. Для быстрой проверки весов без FastAPI можно **`ollama run`** с тем же именем модели, что после `pull` (интерактивный режим Ollama).\n2. **API** — активировать venv, выставить **`NO_PROXY`**, **`DRY_RUN`**, **`OLLAMA_BASE_URL`**, **`OLLAMA_MODEL`**, **`MAX_RETRIES`**, при необходимости **`OLLAMA_NUM_CTX`** / **`OLLAMA_NUM_PREDICT`**, затем **`uvicorn api.main:app --reload --host 127.0.0.1 --port 8080`**.\n3. **Проверка** — `curl http://127.0.0.1:8080/health` или **`python tests/test_sse.py`**.\n4. **Клиент** — интерактивно: **`python cli-client/chat.py`**; веб: **`cd web-ui`**, **`npm install`**, **`npm run dev`**, браузер **`http://localhost:3000`** (при другом хосте API задать **`NEXT_PUBLIC_API_BASE`**).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flifestreamy%2Flocal-lua-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flifestreamy%2Flocal-lua-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flifestreamy%2Flocal-lua-agent/lists"}