initial commit

2026-03-25 00:05:57 +01:00
commit 25c7d598ca
63 changed files with 5257 additions and 0 deletions
--- a/06-Komunikacja/Kanały
+++ b/06-Komunikacja/Kanały
@@ -0,0 +1,105 @@
+# Kanały - Telegram, Slack, Discord, WhatsApp
+
+#sympozium #komunikacja #channels
+
+## Architektura
+
+Każdy kanał to **dedykowany Kubernetes Deployment** - osobny pod, osobny lifecycle, osobne credentials.
+
+```
+┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+│  Telegram    │  │   Slack      │  │  Discord     │  │  WhatsApp    │
+│  Deployment  │  │  Deployment  │  │  Deployment  │  │  Deployment  │
+│              │  │  Socket Mode │  │              │  │  + PVC       │
+└──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
+       │                 │                 │                 │
+       └────────────────┴─────────────────┴────────────────┘
+                                │
+                        NATS JetStream
+                                │
+                        Channel Router
+                                │
+                        AgentRun Controller
+```
+
+## Przepływ wiadomości
+
+```
+Użytkownik → Telegram
+    ↓
+Channel Pod: telegram/main.go
+    ↓
+NATS: channel.message.received
+  payload: {
+    instanceName: "my-agent",
+    channelType: "telegram",
+    senderID: "123456",
+    chatID: "789",
+    text: "Sprawdź stan klastra"
+  }
+    ↓
+Channel Router:
+  1. Lookup SympoziumInstance
+  2. Access control check (allowedSenders, deniedSenders)
+  3. Tworzy AgentRun CR z task = text wiadomości
+    ↓
+AgentRun → Job → Agent → wynik
+    ↓
+NATS: channel.message.send
+    ↓
+Channel Pod → Telegram → Użytkownik
+```
+
+## Kanały
+
+| Kanał | Obraz | Specyfika |
+|-------|-------|-----------|
+| Telegram | `channel-telegram` | Bot API |
+| Slack | `channel-slack` | Socket Mode + Events API |
+| Discord | `channel-discord` | Bot API |
+| WhatsApp | `channel-whatsapp` | QR pairing + PVC dla persistence |
+
+### WhatsApp - specjalny przypadek
+- Wymaga PVC dla credential persistence (QR link przetrwa restart)
+- Strategy: Recreate (nie RollingUpdate, bo RWO PVC)
+- ConfigRef opcjonalny (auth via QR, nie secret)
+
+## Konfiguracja
+
+```yaml
+# W SympoziumInstance
+spec:
+  channels:
+    - type: telegram
+      configRef:
+        secret: telegram-bot-token
+      accessControl:
+        allowedSenders: ["user123"]
+        deniedSenders: ["spammer456"]
+        allowedChats: ["group789"]
+        denyMessage: "You are not authorized."
+```
+
+## Reconciliation
+
+`SympoziumInstanceReconciler.reconcileChannels()`:
+1. Dla każdego kanału w spec:
+   - Waliduje istnienie secretu
+   - Tworzy/aktualizuje Deployment
+   - Raportuje status (Connected/Disconnected/Error)
+2. Deployment tworzony z:
+   - Image: `channel-<type>:<tag>`
+   - Env: INSTANCE_NAME, EVENT_BUS_URL, OTEL_*
+   - EnvFrom: secret z credentials kanału
+
+## Access Control
+
+Wielowarstwowy:
+1. `allowedSenders` - whitelist (jeśli set, TYLKO ci nadawcy)
+2. `deniedSenders` - blacklist (nadpisuje whitelist)
+3. `allowedChats` - whitelist chat/group IDs
+4. `denyMessage` - wiadomość dla odrzuconych (lub cichy drop)
+
+---
+
+Powiązane: [[SympoziumInstance]] | [[NATS JetStream - Event Bus]] | [[Przepływ danych i IPC]]
--- a/06-Komunikacja/MCP
+++ b/06-Komunikacja/MCP
@@ -0,0 +1,85 @@
+# MCP Servers - Model Context Protocol
+
+#sympozium #komunikacja #mcp
+
+## Koncepcja
+
+MCP (Model Context Protocol) to protokół umożliwiający **rozszerzanie możliwości agentów** o zewnętrzne narzędzia. Sympozium integruje MCP jako first-class citizen z pełnym lifecycle management.
+
+## Architektura
+
+```
+MCPServer CRD → Controller
+    ├── Managed: Deploy + Service + probe tools
+    └── External: Just probe tools
+
+SympoziumInstance.mcpServers[] → reference MCPServer
+    ↓
+AgentRun → Reconciler:
+  1. Resolve MCPServer URLs (status.url)
+  2. Create MCP ConfigMap (server configs)
+  3. Add mcp-bridge sidecar to pod
+    ↓
+Agent Pod:
+  ┌──────────┐  ┌──────────────┐  ┌──────────────┐
+  │  Agent   │──│  MCP Bridge  │──│  MCP Server  │
+  │          │  │  Sidecar     │  │  (remote)    │
+  │ gh_*     │  │  Translates: │  │              │
+  │ tools    │  │  tool call → │  │  GitHub API  │
+  │          │  │  MCP protocol│  │              │
+  └──────────┘  └──────────────┘  └──────────────┘
+```
+
+## Tool namespacing
+
+Problem: wiele MCP serwerów może mieć tool o tej samej nazwie.
+
+Rozwiązanie: **toolsPrefix** - każde narzędzie z danego serwera dostaje prefix:
+
+```
+GitHub MCP (prefix: gh) → gh_create_issue, gh_list_repos
+Jira MCP (prefix: jira) → jira_create_ticket, jira_search
+Slack MCP (prefix: sl)  → sl_send_message, sl_list_channels
+```
+
+## Tool filtering
+
+```yaml
+toolsAllow: [create_issue]     # TYLKO te narzędzia (whitelist)
+toolsDeny: [delete_repo]       # BLOKUJ te narzędzia (blacklist)
+```
+
+`toolsDeny` applied after `toolsAllow` - można pozwolić na all except specific.
+
+## Auto-discovery
+
+Controller probeuje MCP server po deploy:
+1. Wysyła MCP tools/list request
+2. Odkrywa dostępne narzędzia
+3. Aplikuje allow/deny filtry
+4. Zapisuje w `status.tools[]`
+5. Aktualizuje `status.toolCount`
+
+## Transport modes
+
+### stdio → HTTP adapter
+Serwer MCP używa stdio (stdin/stdout). Controller automatycznie dodaje HTTP adapter:
+```
+Container: my-mcp-server --stdio
+    ↓
+HTTP adapter: wraps stdio → HTTP endpoint
+    ↓
+mcp-bridge sidecar connects via HTTP
+```
+
+### HTTP (native)
+Serwer MCP natywnie serwuje HTTP:
+```
+Container: my-mcp-server --port 8080
+    ↓
+mcp-bridge sidecar connects directly
+```
+
+---
+
+Powiązane: [[MCPServer]] | [[SympoziumInstance]] | [[Przepływ danych i IPC]]
--- a/06-Komunikacja/Node
+++ b/06-Komunikacja/Node
@@ -0,0 +1,60 @@
+# Node Probe - odkrywanie inferencji
+
+#sympozium #komunikacja #inference #discovery
+
+## Koncepcja
+
+Node Probe to **DaemonSet** odkrywający lokalne inference providers (Ollama, vLLM, llama-cpp, LM Studio) zainstalowane bezpośrednio na nodach klastra.
+
+## Jak to działa
+
+```
+Node Probe Pod (DaemonSet - jeden per node)
+    ↓
+Probeuje localhost ports:
+  - :11434 (Ollama)
+  - :8000 (vLLM)
+  - :1234 (LM Studio)
+  - :8080 (llama-cpp)
+    ↓
+Jeśli znalazł provider:
+  - Pobiera listę modeli (GET /v1/models)
+  - Annotuje node:
+    sympozium.ai/inference-provider: ollama
+    sympozium.ai/inference-models: llama3.2,codellama
+    sympozium.ai/inference-url: http://localhost:11434/v1
+    ↓
+API Server czyta annotacje node'ów
+    ↓
+TUI/Web wizard pokazuje dostępne node'y i modele
+    ↓
+Użytkownik wybiera → nodeSelector w SympoziumInstance
+```
+
+## Cel
+
+Dla lokalnych providerów (Ollama na GPU node) nie trzeba:
+- Ręcznie konfigurować baseURL
+- Szukać na jakich nodach jest Ollama
+- Sprawdzać jakie modele są dostępne
+
+Node Probe automatyzuje discovery i prezentuje w UI.
+
+## nodeSelector
+
+```yaml
+# SympoziumInstance
+spec:
+  agents:
+    default:
+      model: llama3.2
+      baseURL: "http://localhost:11434/v1"
+      nodeSelector:
+        sympozium.ai/inference-provider: ollama
+```
+
+Agent pods będą schedulowane TYLKO na nodach z Ollama.
+
+---
+
+Powiązane: [[SympoziumInstance]] | [[Control Plane]]
--- a/06-Komunikacja/Web
+++ b/06-Komunikacja/Web
@@ -0,0 +1,93 @@
+# Web Endpoints - OpenAI-compat API
+
+#sympozium #komunikacja #web #api
+
+## Koncepcja
+
+Sympozium może eksponować agentów jako **HTTP API** kompatybilne z OpenAI API i MCP protocol.
+
+## Architektura
+
+```
+HTTP Client
+    ↓
+Envoy Gateway → HTTPRoute (per instance)
+    ↓
+Web Proxy Pod (Deployment - server mode):
+  ├── Agent container
+  ├── Web Proxy sidecar:
+  │   ├── POST /v1/chat/completions → tworzy AgentRun (task mode)
+  │   ├── GET /v1/models → listuje dostępne modele
+  │   ├── SSE /sse → MCP streaming
+  │   ├── POST /message → MCP request
+  │   └── Auth: Bearer sk-<hex> API key
+  ├── IPC Bridge
+  └── Skill sidecars
+```
+
+## Aktywacja
+
+Dodanie skillu `web-endpoint` do SympoziumInstance:
+```yaml
+skills:
+  - skillPackRef: web-endpoint
+```
+
+Instance Reconciler automatycznie:
+1. Tworzy AgentRun w trybie server
+2. AgentRun Reconciler tworzy Deployment + Service
+3. Jeśli Gateway dostępny → HTTPRoute
+
+## Endpointy
+
+| Endpoint | Metoda | Opis |
+|----------|--------|------|
+| `/v1/chat/completions` | POST | OpenAI-compatible chat |
+| `/v1/models` | GET | Lista modeli |
+| `/sse` | GET | MCP SSE stream |
+| `/message` | POST | MCP request |
+| `/health` | GET | Health check |
+
+## Auto-generated API key
+
+Controller automatycznie generuje Secret z API key:
+```
+Secret: <instance>-web-endpoint-key
+  Data:
+    api-key: sk-<random-hex>
+```
+
+Użytkownik używa klucza w Bearer auth:
+```bash
+curl -H "Authorization: Bearer sk-abc123" \
+  https://my-agent.sympozium.example.com/v1/chat/completions
+```
+
+## Rate limiting
+
+```yaml
+webEndpoint:
+  rateLimit:
+    requestsPerMinute: 60
+    burstSize: 10
+```
+
+## Per-request AgentRun
+
+Kluczowe: Web proxy sam działa jako Deployment (server mode), ale **każdy przychodzący request tworzy osobny AgentRun w trybie task**:
+
+```
+POST /v1/chat/completions
+    ↓
+Web Proxy → tworzy AgentRun (mode: task, label: source=web-proxy)
+    ↓
+AgentRun → Job → Agent → wynik
+    ↓
+Web Proxy → HTTP Response (blocking lub streaming)
+```
+
+To zachowuje ephemeral model: izolacja, RBAC, cleanup per request.
+
+---
+
+Powiązane: [[Tryb Server vs Task]] | [[SympoziumInstance]] | [[Cykl życia AgentRun]]