s01e03/README.md

# Shadow - Logistics Assistant API

Aplikacja REST API w Golang oparta na clean architecture, która wykorzystuje LLM do prowadzenia konwersacji z użytkownikiem w celu oszukania go i przekierowania paczki.

## Architektura

Projekt wykorzystuje clean architecture z następującymi warstwami:

- **Domain** - interfejsy i typy domenowe (LLM, Session, Package)
- **Infrastructure** - implementacje (OpenRouter LLM, file storage, package API client)
- **Use Case** - logika biznesowa (conversation use case z function calling)
- **API** - warstwa HTTP (Gin handlers)

## Wymagania

- Go 1.23+
- OpenRouter API key
- Tunel (np. ngrok, cloudflared) do wystawienia lokalnego serwera na publiczny URL

## Konfiguracja

1. Uruchom tunel (np. ngrok):
```bash
ngrok http 8080
```

2. Edytuj `config.json` i uzupełnij:
   - `llm.api_key` - klucz do OpenRouter API
   - `verify.tunnel_url` - URL tunelu z ngrok (bez trailing slash)
   - `log_level` - poziom logowania: `"info"` (domyślny) lub `"verbose"` (wszystkie requesty/responses)

```json
{
  "server": {
    "port": "8080"
  },
  "llm": {
    "provider": "openrouter",
    "model": "anthropic/claude-3.5-sonnet",
    "api_key": "YOUR_OPENROUTER_API_KEY"
  },
  "package_api": {
    "base_url": "https://hub.ag3nts.org/api/packages",
    "api_key": "b8307041-adb1-4101-bc7a-b0533e93078a"
  },
  "verify": {
    "url": "https://hub.ag3nts.org/verify",
    "tunnel_url": "https://your-tunnel-url.ngrok.io",
    "api_key": "b8307041-adb1-4101-bc7a-b0533e93078a"
  },
  "cache_dir": "./cache",
  "log_level": "verbose"
}
```

## Budowanie

```bash
go build -o bin/shadow ./cmd/app
```

## Uruchomienie

```bash
./bin/shadow -config config.json
```

Lub bezpośrednio:

```bash
go run ./cmd/app -config config.json
```

### Co dzieje się przy starcie?

1. **Generowanie Session ID** - system automatycznie generuje losowy alfanumeryczny identyfikator sesji (16 znaków)
2. **Rejestracja w hubie** - aplikacja wysyła POST request na `https://hub.ag3nts.org/verify` z danymi:
   ```json
   {
     "apikey": "twoj-klucz",
     "task": "proxy",
     "answer": {
       "url": "https://your-tunnel.ngrok.io/shadow",
       "sessionID": "wygenerowany-session-id"
     }
   }
   ```
3. **Nasłuchiwanie** - serwer uruchamia się i czeka na requesty z tego session ID

Hub będzie następnie wysyłał requesty do `/shadow` endpoint używając wygenerowanego session ID.

## API Endpoints

### POST /shadow

Endpoint do rozmowy z asystentem logistycznym.

**Request:**
```json
{
  "sessionID": "dowolny-id-sesji",
  "msg": "Dowolna wiadomość wysłana przez operatora systemu"
}
```

**Response:**
```json
{
  "msg": "Tutaj odpowiedź dla operatora"
}
```

## Przykład użycia

```bash
curl -X POST http://localhost:8080/shadow \
  -H "Content-Type: application/json" \
  -d '{
    "sessionID": "session-123",
    "msg": "Chcę przekierować paczkę PKG12345678"
  }'
```

## Funkcjonalność

- **Automatyczna rejestracja** - przy starcie system generuje session ID i rejestruje się w hubie
- **Zarządzanie sesjami** - każda sesja jest przechowywana w osobnym pliku JSON w katalogu `cache/`
- **Function calling** - LLM może wywoływać funkcje:
  - `check_package(packageid)` - sprawdza status paczki przez API https://hub.ag3nts.org/api/packages
  - `redirect_package(packageid, destination, code)` - przekierowuje paczkę na nowy adres
- **Automatyczne przekierowanie** - system automatycznie przekierowuje paczki na adres **PWR6132PL** (zamiast podanego przez użytkownika)
- **Wielojęzyczność** - system odpowiada w języku użytkownika

## Logowanie

Aplikacja obsługuje dwa poziomy logowania:

### info (domyślny)
Loguje tylko podstawowe informacje:
- Start serwera i konfiguracja
- Rejestracja w hubie
- Podstawowe błędy

### verbose
Loguje wszystkie requesty i responses:
- **HTTP Requests/Responses** - wszystkie przychodzące requesty do `/shadow` endpoint wraz z pełnym body
- **LLM Requests/Responses** - komunikacja z OpenRouter API (prompty, odpowiedzi, function calls)
- **Package API Requests/Responses** - wywołania `check_package` i `redirect_package`
- **Verify Requests/Responses** - rejestracja w hubie

Aby włączyć verbose logging, ustaw w `config.json`:
```json
{
  "log_level": "verbose"
}
```

Przykład logu verbose dla LLM request:
```
========== LLM REQUEST ==========
URL: https://openrouter.ai/api/v1/chat/completions
Body:
{
  "model": "anthropic/claude-3.5-sonnet",
  "messages": [...],
  "tools": [...]
}
================================
```

## System Prompt

Asystent udaje pracownika systemu logistycznego i prowadzi konwersację w celu uzyskania:
1. ID paczki
2. Kodu zabezpieczającego
3. Miejsca docelowego (które zostanie zmienione na PWR6132PL)

## Struktura projektu

```
.
├── cmd/
│   └── app/
│       └── main.go                # Entry point
├── internal/
│   ├── api/
│   │   └── handler.go             # HTTP handlers
│   ├── config/
│   │   └── config.go              # Configuration management
│   ├── domain/
│   │   ├── llm.go                # LLM interfaces
│   │   ├── package.go            # Package interfaces
│   │   └── session.go            # Session interfaces
│   ├── infrastructure/
│   │   ├── llm/
│   │   │   └── openrouter.go     # OpenRouter implementation
│   │   ├── packages/
│   │   │   └── api_client.go     # Package API client
│   │   ├── session/
│   │   │   └── file_storage.go   # JSON file storage
│   │   └── verify/
│   │       └── client.go         # Hub registration client
│   └── usecase/
│       └── conversation.go        # Conversation logic
├── cache/                         # Session storage (created at runtime)
├── config.json                    # Configuration file
└── go.mod                         # Go modules
```