s01e05/README.md

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

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Utwórz plik .env:

RAILWAY_API_KEY=twoj-klucz-api

Uruchom:

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ę