initial commit

README.md

@@ -0,0 +1,61 @@
+# S01E05 — Railway Route Activator
+
+Aplikacja aktywująca trasę kolejową **X-01** przez API `hub.ag3nts.org`.
+Zadanie z kursu AI Devs 4 — zarządzanie jawnymi oraz niejawnymi limitami modeli.
+
+## Architektura (Clean Architecture)
+
+```
+domain/              # Encje i porty (interfejsy)
+├── entities.py      # Route, RouteStatus, RouteMode, ApiResponse
+└── ports.py         # RailwayApiPort, EventBusPort
+
+application/         # Use case'y (logika biznesowa)
+└── activate_route.py
+
+infrastructure/      # Implementacje
+├── api_client.py    # Klient API z retry i obsługą limitów
+├── config.py        # Konfiguracja z .env
+├── event_bus.py     # Szyna zdarzeń
+└── logger_setup.py  # Logowanie i monitoring zdarzeń
+
+main.py              # Punkt wejścia
+```
+
+### Koncepcje z lekcji
+
+- **Event-driven architecture** — `EventBus` emituje zdarzenia (`api:request`, `api:response`, `api:retry`, `workflow:step`) umożliwiając monitoring i reakcję na zmiany stanu
+- **Obsługa limitów API** — automatyczny retry z respektowaniem `retry_after` przy 429
+- **Obsługa błędów 503** — retry z backoff (symulacja przeciążenia serwera)
+- **Heartbeat** — logi informujące o postępie każdego kroku workflow
+- **Logowanie interakcji** — każde wywołanie i odpowiedź API jest rejestrowane
+- **Dependency Injection** — porty (abstrakcje) w `domain/`, implementacje w `infrastructure/`
+
+## Uruchomienie
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Utwórz plik `.env`:
+
+```env
+RAILWAY_API_KEY=twoj-klucz-api
+```
+
+Uruchom:
+
+```bash
+python main.py          # domyślnie trasa x-01
+python main.py x-01     # lub jawnie podaj nazwę trasy
+```
+
+## Sekwencja API
+
+1. `help` — pobranie dokumentacji API
+2. `getstatus` — sprawdzenie bieżącego statusu trasy
+3. `reconfigure` — włączenie trybu rekonfiguracji
+4. `setstatus` (RTOPEN) — otwarcie trasy
+5. `save` — zapisanie zmian, zwraca flagę