# 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.