107 lines
4.7 KiB
Markdown
107 lines
4.7 KiB
Markdown
# agentic-codemod-pipeline
|
|
|
|
Repozytorium wzorcowe: **sieć agentowa (agno) modyfikująca kod, zasilana kontekstem
|
|
z pakietów APM, uruchamiana jako pipeline w GitLab CI.**
|
|
|
|
Przykładowy przypadek użycia: podniesienie wersji SDK wraz z migracją wywołań API.
|
|
|
|
```bash
|
|
brew install go-task # albo: pip install go-task-bin
|
|
|
|
task install # .venv + zależności
|
|
task test # 46 testów, bez modelu językowego
|
|
task demo # pełny przebieg na fixture, offline
|
|
task --list # reszta zadań
|
|
```
|
|
|
|
Wszystko dzieje się w lokalnym `.venv` - nic nie trafia do systemowego Pythona.
|
|
Gdy coś nie działa, zacznij od `task doctor`.
|
|
|
|
## Skąd się bierze zachowanie agentów
|
|
|
|
Z pakietu APM, nie z kodu:
|
|
|
|
```
|
|
.apm/
|
|
├── agents/ scout, planner, coder, reviewer, scribe (model, narzędzia, schemat wyjścia)
|
|
├── skills/ repo-recon, sdk-version-upgrade, safe-code-edit, merge-request-authoring
|
|
├── instructions/ guardraile bezpieczeństwa, konwencje języka
|
|
├── prompts/ wsad zadania (sdk-upgrade, dependency-audit)
|
|
└── context/ kontrakt przebiegu wspólny dla wszystkich ról
|
|
```
|
|
|
|
`apm.yml` deklaruje, skąd przychodzi reszta kontekstu; `apm-policy.yml` ogranicza, co wolno
|
|
zainstalować; `apm.lock.yaml` pinuje wersje. Silnik w `src/agentic_codemod/` kompiluje
|
|
te prymitywy do obiektów agno - nie zawiera ani jednego zaszytego promptu.
|
|
|
|
## Przepływ
|
|
|
|
```
|
|
intake → recon → plan → [bump wersji → pętla(implement → verify) → review → opis MR] → bramka CI → MR
|
|
```
|
|
|
|
Kroki deterministyczne (wykrycie ekosystemu, podbicie wersji, uruchomienie testów, git)
|
|
robi kod. Model dostaje tylko to, czego nie da się zrobić inaczej. Szczegóły podziału:
|
|
[docs/architecture.md](docs/architecture.md).
|
|
|
|
## Trzy tryby, jedna topologia
|
|
|
|
| Tryb | Mózg | Zastosowanie |
|
|
|---|---|---|
|
|
| `--offline` | reguły codemod z pakietu APM | smoke test pipeline'u, bez GPU i bez internetu |
|
|
| domyślny + backend `mock` | agenci agno na atrapie serwera OpenAI | test ścieżki agentowej w CI: narzędzia, schematy, pętla weryfikacji |
|
|
| domyślny + realny model | agenci agno na vLLM | przypadki wykraczające poza reguły |
|
|
|
|
## Model językowy od zera
|
|
|
|
Nie ma jednej komendy uruchamiającej vLLM na Linuksie i na macOS - Docker na Macu
|
|
nie ma dostępu do Metala. Kontrakt jest jeden (endpoint zgodny z OpenAI), a backend
|
|
dobiera się do platformy sam:
|
|
|
|
```bash
|
|
task llm:list # co jest dostępne i co pasuje do tej maszyny
|
|
task llm:up # Linux+NVIDIA -> vLLM w kontenerze, macOS -> vllm-metal (MLX)
|
|
eval "$(task llm:env)" # zmienne dla silnika
|
|
task llm:logs # podgląd logów backendu na żywo
|
|
task demo:llm # przebieg agentowy na fixture
|
|
task llm:down
|
|
```
|
|
|
|
Wybór ręczny: `LLM_BACKEND=ollama task llm:up`, `LLM_BACKEND=mock task demo:llm`.
|
|
Konfiguracja backendów i modeli per rola: [`llm/models.yml`](llm/models.yml).
|
|
|
|
## Dokumentacja
|
|
|
|
- [Architektura](docs/architecture.md) - warstwy, przepływ, model bezpieczeństwa, granice
|
|
- [Runbook](docs/runbook.md) - uruchamianie, kody wyjścia, typowe sytuacje, rozszerzanie
|
|
- ADR: [APM jako łańcuch dostaw kontekstu](docs/adr/0001-apm-jako-lancuch-dostaw-kontekstu.md) ·
|
|
[Deterministycznie vs model](docs/adr/0002-podzial-na-krok-deterministyczny-i-model.md) ·
|
|
[Runtime w jobie CI](docs/adr/0003-runtime-w-efemerycznym-jobie-gitlab-ci.md) ·
|
|
[Guardraile w dwóch warstwach](docs/adr/0004-guardraile-w-dwoch-warstwach.md) ·
|
|
[Backend LLM per platforma](docs/adr/0005-backend-llm-per-platforma.md)
|
|
|
|
## Struktura
|
|
|
|
```
|
|
.apm/ kontekst agentowy (źródło prawdy o zachowaniu sieci)
|
|
src/agentic_codemod/
|
|
├── apm/ ładowanie prymitywów APM i kompilacja do agno
|
|
├── adapters/ pip / maven / npm - wiedza deterministyczna o ekosystemie
|
|
├── tools/ sandboxowane narzędzia agenta (pliki, weryfikacja, git)
|
|
├── workflow/ topologia agno, kroki, reguły codemod, uruchamianie
|
|
├── observability/ ślad audytowy z redakcją sekretów
|
|
└── integrations/ GitLab (merge request, komentarze)
|
|
llm/ backendy LLM: models.yml, docker-compose, vllm-metal, atrapa serwera OpenAI
|
|
examples/fixtures/acme-app aplikacja na SDK 1.x + atrapa SDK 2.x (test regresyjny e2e)
|
|
.gitlab/ci/ szablon do include w repozytoriach docelowych
|
|
ci/ obraz runnera
|
|
```
|
|
|
|
## Wymagania
|
|
|
|
Python 3.10+, git, ripgrep. Do instalacji kontekstu: APM CLI.
|
|
|
|
Do przebiegu z modelem wystarczy `task llm:up`: na Linuksie z GPU NVIDIA potrzebny
|
|
Docker, na macOS Apple Silicon - arm64 Python 3.12 i Xcode Command Line Tools.
|
|
Testy i tryb offline nie wymagają niczego z tej listy.
|