twinshare 0.1.43
Twin Share - Environment Manager - narzędzie do dzielenia się środowiskami Embedded/AI/VM
Requires Python: >=3.8

# share
# Podsumowanie projektu AI Environment Manager

kompleksowe rozwiązanie do zarządzania, udostępniania i klonowania środowisk AI w sieci lokalnej. Poniżej przedstawiam kluczowe dokumenty i wytyczne dla dalszego rozwoju projektu.

## Główne dokumenty

1. **[Dokumentacja](docs/index.md)** - Kompletna dokumentacja projektu z menu wszystkich dostępnych przewodników
2. **[Architektura systemu](docs/architecture.md)** - Szczegółowa architektura systemu, opis komponentów i ich interakcji
3. **[Podręcznik użytkownika](docs/user_guide.md)** - Kompletna instrukcja obsługi dla użytkowników końcowych
4. **[Przewodnik testowania](docs/tests.md)** - Metodologia i scenariusze testowe dla deweloperów
5. **[Instalacja i konfiguracja](docs/installation.md)** - Szczegółowe instrukcje instalacji i konfiguracji na różnych platformach
6. **[REST API Guide](docs/rest_api_guide.md)** - Kompletna dokumentacja REST API
7. **[P2P Networking](docs/p2p_networking.md)** - Dokumentacja funkcjonalności sieci P2P
8. **[VM Sharing Guide](docs/vm_sharing_guide.md)** - Przewodnik udostępniania maszyn wirtualnych

## Kluczowe moduły zaimplementowane

1. **P2P Discovery** - Moduł automatycznego wykrywania węzłów w sieci lokalnej
2. **Core Workspace** - Podstawowy model danych dla workspace'ów, projektów i środowisk
3. **REST API Server** - Pełne REST API do zarządzania systemem, VM i P2P
4. **REST API Client** - Biblioteka kliencka do integracji z API

## Unikalne cechy rozwiązania

1. **Architektura P2P** - System działa w modelu peer-to-peer bez centralnego serwera
2. **Federacja węzłów** - Możliwość rozproszenia obciążeń między wieloma maszynami
3. **Wieloplatformowość** - Wsparcie dla różnych systemów operacyjnych i środowisk wykonawczych
4. **One-Click Deployment** - Możliwość sklonowania środowiska jednym kliknięciem
5. **Automatyczna adaptacja** - Dostosowanie do dostępnych zasobów sprzętowych
6. **REST API** - Pełne REST API do integracji z zewnętrznymi systemami

## Instalacja

### Instalacja bezpośrednio z PyPI

Najłatwiejszym sposobem instalacji jest użycie pip do zainstalowania pakietu bezpośrednio z PyPI:

```bash
pip install twinshare
```

Po instalacji, komenda `twinshare` będzie dostępna bezpośrednio w terminalu:

```bash
# Sprawdź dostępne komendy
twinshare --help

# Zarządzanie maszynami wirtualnymi
twinshare vm list

# Zarządzanie siecią P2P
twinshare p2p discover

# Zarządzanie serwerem REST API
twinshare api start --host 0.0.0.0 --port 8000  # Uruchamia serwer REST API
twinshare api start --daemon                    # Uruchamia serwer w tle
twinshare api status                            # Sprawdza status serwera
twinshare api stop                              # Zatrzymuje serwer REST API

# Zarządzanie przestrzeniami roboczymi
twinshare workspace list
```

Komenda `twinshare` jest dostępna natychmiast po instalacji, bez potrzeby konfiguracji dodatkowych skryptów czy zmiennych środowiskowych.

### Instalacja na nowym systemie z repozytorium

Aby zainstalować twinshare z repozytorium, użyj dedykowanego skryptu `install_package.sh`:

```bash
# Sklonuj repozytorium
git clone https://github.com/safetytwin/share.git
cd share

# Uruchom skrypt instalacyjny
./install_package.sh
```

Skrypt przeprowadzi Cię przez proces instalacji, oferując instalację w środowisku wirtualnym lub systemową.

### Automatyczna instalacja

Użyj skryptu instalacyjnego, który zainstaluje wszystkie wymagane zależności i skonfiguruje usługi:

```bash
# Pełna instalacja
./install.sh

# Instalacja z pominięciem zależności systemowych
./install.sh --skip-system-deps

# Instalacja z pominięciem usługi systemowej
./install.sh --skip-service-install

# Instalacja w trybie nieinteraktywnym
./install.sh --non-interactive
```

### Ręczna instalacja

1. Zainstaluj wymagane zależności systemowe:

```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-venv libvirt-dev pkg-config \
    libvirt-daemon libvirt-daemon-system qemu-kvm bridge-utils virtinst \
    libvirt-clients build-essential python3-dev

# Fedora/CentOS/RHEL
sudo dnf update -y
sudo dnf install -y python3 python3-pip python3-virtualenv libvirt-devel \
    pkgconfig libvirt libvirt-daemon-kvm qemu-kvm bridge-utils \
    virt-install libvirt-client gcc python3-devel
```

2. Utwórz i aktywuj wirtualne środowisko Python:

```bash
python3 -m venv venv
source venv/bin/activate
```

3. Zainstaluj zależności Pythona:

```bash
pip install -e .
```

## Rozwiązywanie problemów z CLI

Jeśli po instalacji komenda `twinshare` nie jest dostępna:

1. Sprawdź, czy skrypt instalacyjny zakończył się sukcesem
2. Sprawdź, czy symlink został utworzony: `which twinshare`
3. Jeśli używasz środowiska wirtualnego, upewnij się, że jest aktywowane: `source venv/bin/activate`
4. Spróbuj uruchomić CLI bezpośrednio: `python3 -m src.cli.main --help`
5. Możesz również użyć skryptu w katalogu bin: `./bin/twinshare --help`

## Uruchomienie REST API

### Jako usługa systemowa

1. Zainstaluj usługę:

```bash
# Utwórz katalogi dla logów i PID
sudo mkdir -p /var/log/twinshare /var/run/twinshare

# Skopiuj plik usługi
sudo cp scripts/twinshare-rest-api.service /etc/systemd/system/

# Załaduj konfigurację systemd
sudo systemctl daemon-reload

# Włącz usługę do autostartu
sudo systemctl enable twinshare-rest-api

# Uruchom usługę
sudo systemctl start twinshare-rest-api

# Sprawdź status
sudo systemctl status twinshare-rest-api
```

### Ręczne uruchomienie

```bash
# Uruchom w trybie foreground
python scripts/start_rest_api.py start --foreground

# Uruchom jako daemon
python scripts/start_rest_api.py start

# Sprawdź status
python scripts/start_rest_api.py status

# Zatrzymaj
python scripts/start_rest_api.py stop
```

## Przykłady użycia REST API

Zobacz [przykłady użycia REST API](examples/rest_api_usage.py) oraz [dokumentację REST API](docs/rest_api_guide.md).

## Kolejne kroki

1. **Implementacja modułów wykonawczych** (Runtime) - Użyj promptu dla modułów VM, Container i Process
2. **Rozwój interfejsu webowego** - Stwórz nowoczesny UI w React z komunikacją przez WebSocket
3. **Implementacja modułu Repository i Transfer** - Dokończ implementację mechanizmów udostępniania
4. **Testy** - Stwórz komplet testów jednostkowych i integracyjnych
5. **Dokumentacja użytkownika** - Uzupełnij dokumentację o więcej przykładów i przypadków użycia

To rozwiązanie, inspirowane systemami takimi jak LocalAI z funkcjami P2P, Codezero i integracja Conda z JuiceFS, zapewnia bezproblemowe zarządzanie środowiskami AI w zespołach deweloperskich, pozwalając na natychmiastowe rozpoczęcie pracy bez skomplikowanej konfiguracji środowiska.

# Specyfikacja funkcjonalna: AI Environment Manager

## 1. Cel systemu

Stworzenie rozwiązania umożliwiającego proste udostępnianie i klonowanie gotowych środowisk programistycznych dla projektów AI między komputerami w sieci lokalnej. System zapewnia natychmiastowy dostęp do skonfigurowanych narzędzi i projektów bez konieczności ręcznej konfiguracji.

## 2. Główne funkcjonalności

### 2.1. Automatyczne wykrywanie i udostępnianie

- Automatyczne wykrywanie hostów w sieci lokalnej udostępniających środowiska AI
- Rozgłaszanie dostępnych środowisk w sieci lokalnej (zero-configuration networking)
- Przeglądanie dostępnych środowisk z poziomu interfejsu przeglądarki
- Filtrowanie i wyszukiwanie środowisk według typów, narzędzi i języków

### 2.2. Zarządzanie środowiskami

- Tworzenie, edycja i usuwanie workspace'ów z projektami AI
- Włączanie/wyłączanie udostępniania workspace'ów dla innych użytkowników
- Eksportowanie i importowanie workspace'ów
- Automatyczne przydzielanie zasobów (CPU, RAM, dysk) dla środowisk

### 2.3. Klonowanie środowisk

- Jednym kliknięciem pobranie wybranego środowiska z innego komputera w sieci
- Automatyczna konfiguracja pobranego środowiska
- Adaptacja środowiska do zasobów lokalnego komputera
- Automatyczne uruchamianie środowiska po pobraniu

### 2.4. Dostęp do środowisk

- Dostęp przez przeglądarkę do wszystkich narzędzi w środowisku
- Automatyczne logowanie do narzędzi (VSCode, JupyterLab, Le Chat)
- Zintegrowany terminal dostępny z poziomu interfejsu www
- Automatyczne uruchamianie środowisk przy starcie systemu

### 2.5. Integracja z projektami

- Automatyczne klonowanie repozytoriów git podczas pobierania środowiska
- Automatyczna konfiguracja środowiska na podstawie plików konfiguracyjnych projektu
- Synchronizacja zmian między projektami w różnych workspace'ach
- Integracja z narzędziami CI/CD

## 3. Komponenty systemu

### 3.1. Moduł wykrywania (Discovery)

- Protokół rozgłaszania dostępnych środowisk w sieci lokalnej
- Mechanizm automatycznego wykrywania hostów w sieci
- Protokół pobierania metadanych o dostępnych środowiskach
- Wykrywanie dostępnych zasobów na komputerze

### 3.2. Moduł udostępniania (Sharing)

- Serwer HTTP do udostępniania plików
- Kompresja i szyfrowanie przesyłanych danych
- Mechanizm autoryzacji dostępu do środowisk
- System kolejkowania równoczesnych transferów

### 3.3. Moduł zarządzania (Management)

- Tworzenie i konfiguracja workspace'ów
- Zarządzanie projektami w workspace'ach
- Zarządzanie środowiskami (VM, kontenery, procesy lokalne)
- System przydzielania zasobów sprzętowych

### 3.4. Interfejs webowy (Web UI)

- Panel dostępny przez przeglądarkę
- Intuicyjny interfejs one-click-deployment
- Dashboard z przeglądem środowisk
- Zarządzanie procesem pobierania i udostępniania

## 4. Wymagania techniczne

### 4.1. Wymagania sprzętowe (minimum)

- CPU: 2 rdzenie
- RAM: 4 GB
- Dysk: 20 GB wolnego miejsca
- Sieć: Dostęp do sieci lokalnej

### 4.2. Wymagania sprzętowe (zalecane)

- CPU: 8+ rdzeni
- RAM: 16+ GB
- Dysk: 100+ GB wolnego miejsca (najlepiej SSD)
- Sieć: Gigabit Ethernet

### 4.3. Wymagania programowe

- Python 3.8+
- Zależności systemowe: libvirt/QEMU, Docker/Podman (opcjonalnie)
- Przeglądarka internetowa: Chrome, Firefox, Edge (najnowsze wersje)

## 5. Interakcje użytkownika

### 5.1. Udostępnianie środowiska

1. Użytkownik uruchamia aplikację na swoim komputerze
2. Wybiera workspace do udostępnienia
3. Klika przycisk "Udostępnij"
4. System automatycznie rozgłasza dostępność środowiska w sieci

### 5.2. Pobieranie środowiska

1. Użytkownik uruchamia aplikację na swoim komputerze
2. Przegląda listę dostępnych środowisk w sieci
3. Wybiera interesujące go środowisko
4. Klika przycisk "Pobierz"
5. System automatycznie pobiera, konfiguruje i uruchamia środowisko

### 5.3. Uruchamianie środowiska

1. Użytkownik wybiera pobrany workspace
2. Klika przycisk "Uruchom"
3. System uruchamia wszystkie komponenty środowiska
4. Użytkownik otrzymuje linki do dostępu przez przeglądarkę

## 6. Protokoły i formaty danych

### 6.1. Protokół wykrywania

- Multicast UDP na porcie 37777
- Format danych: Skompresowany JSON z informacjami o hoście i dostępnych środowiskach
- Interwał rozgłaszania: 10 sekund

### 6.2. Protokół udostępniania

- HTTP/REST API na porcie 37778
- Format danych: JSON dla metadanych, ZIP dla transferu środowisk
- Autoryzacja: Podstawowa autoryzacja nagłówków HTTP

### 6.3. Format workspace'u

- Katalog z plikami YAML zawierającymi konfigurację
- Podkatalogi dla projektów, środowisk i danych
- Wersjonowanie konfiguracji
- Skrypty inicjalizacyjne dla różnych platform

## 7. Bezpieczeństwo

- Ograniczenie udostępniania tylko do sieci lokalnej
- Opcjonalne szyfrowanie transferów
- Walidacja integralności pobranych danych
- Sandbox dla uruchamianych środowisk

## 8. Rozszerzalność

- Plugin API dla dodawania nowych typów środowisk
- Wsparcie dla skryptów niestandardowych
- Możliwość dodawania własnych szablonów środowisk
- Integracja z dodatkowymi narzędziami AI