feat: initial commit

2026-08-29 13:17:59 +02:00
commit 142f5f5759
91 changed files with 6155 additions and 0 deletions
@@ -0,0 +1,106 @@
+# 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.