initial commit

2026-03-25 00:05:57 +01:00
commit 25c7d598ca
63 changed files with 5257 additions and 0 deletions
--- a/01-Przegląd/Czym
+++ b/01-Przegląd/Czym
@@ -0,0 +1,57 @@
+# Czym jest Sympozium
+
+#sympozium #przegląd
+
+## Definicja
+
+Sympozium to **Kubernetes-natywna platforma orkiestracji agentów AI** napisana w Go. Każdy agent AI działa jako efemeryczny pod Kubernetes (Job), z wymuszaniem polityk przez CRD, admission webhooks i RBAC. Komunikacja odbywa się przez NATS JetStream i IPC oparty na systemie plików.
+
+## Dwa przypadki użycia
+
+Sympozium obsługuje dwa potężne scenariusze na jednej platformie:
+
+### 1. Orkiestracja flot agentów AI
+- Customer support, code review, data pipelines, dowolne workflow domenowe
+- Każdy agent dostaje własny pod, RBAC i network policy z izolacją tenanta
+
+### 2. Agentowe administrowanie klastrem
+- Agenty skierowane "do wewnątrz" - diagnoza awarii, skalowanie, triage alertów, remediacja
+- Pełna izolacja, RBAC i audit trail na poziomie Kubernetes
+
+## Kluczowe cechy
+
+| Cecha | Opis |
+|-------|------|
+| **[[PersonaPack\|PersonaPacks]]** | Bundle'e Helm-like dla agentów - aktywuj pack, controller tworzy cały zespół |
+| **[[Skill Sidecars i auto-RBAC\|Skill Sidecars]]** | Każdy skill w osobnym sidecarze z efemerycznym RBAC least-privilege |
+| **Multi-Channel** | Telegram, Slack, Discord, WhatsApp - każdy kanał jako dedykowany Deployment |
+| **[[Persistent Memory]]** | SQLite + FTS5 na PersistentVolume - pamięć przetrwa restarty podów |
+| **Scheduled Heartbeats** | Cron-owe uruchomienia agentów: health checks, alert triage, right-sizing |
+| **[[Agent Sandbox - gVisor i Kata\|Agent Sandbox]]** | Izolacja na poziomie kernela via gVisor/Kata z warm pools |
+| **[[MCPServer\|MCP Servers]]** | External tool providers via Model Context Protocol |
+| **TUI & Web UI** | Dashboardy terminalowe i przeglądarkowe |
+| **Any AI Provider** | OpenAI, Anthropic, Azure, Ollama - bez vendor lock-in |
+
+## Technologia
+
+- **Język:** Go 1.25+
+- **Moduł:** `github.com/sympozium-ai/sympozium`
+- **K8s API:** `sympozium.ai/v1alpha1`
+- **Licencja:** Apache 2.0
+- **Autor:** twórca [[https://github.com/k8sgpt-ai/k8sgpt|k8sgpt]] i [[https://github.com/AlexsJones/llmfit|llmfit]]
+
+## Filozofia projektu
+
+> "From Kubernetes, for Kubernetes"
+
+Projekt traktuje Kubernetes nie jako platformę deploymentu, ale jako **framework orkiestracji agentów**. Każdy koncept (agent, polityka, skill, schedule) jest wyrażony jako CRD i zarządzany przez dedykowany controller. To podejście pozwala na:
+
+- **Deklaratywność** - stan pożądany opisany w YAML
+- **Reconciliation loops** - automatyczne naprawianie driftu
+- **ownerReferences** - automatyczne garbage collection
+- **RBAC** - natywna wielotenancja
+- **NetworkPolicy** - natywna izolacja sieciowa
+
+---
+
+Powiązane: [[Kluczowe decyzje projektowe]] | [[Control Plane]] | [[Struktura repozytorium]]
--- a/01-Przegląd/Kluczowe
+++ b/01-Przegląd/Kluczowe
@@ -0,0 +1,64 @@
+# Kluczowe decyzje projektowe
+
+#sympozium #architektura #design-decisions
+
+## Tabela decyzji
+
+| Decyzja | Prymityw K8s | Uzasadnienie |
+|---------|-------------|--------------|
+| **Jeden [[Pod]] per agent run** | [[Job]] | Izolacja blast-radius, limity zasobów, automatyczne czyszczenie |
+| **Filesystem IPC** | emptyDir volume | Agent pisze do `/ipc/`, [[Sidecar Pattern\|bridge sidecar]] obserwuje via fsnotify i publikuje do [[NATS JetStream]] |
+| **[[NATS JetStream]]** | [[StatefulSet]] | Durable pub/sub z replay - kanały i control plane bez bezpośredniego couplingu |
+| **[[NetworkPolicy]] isolation** | NetworkPolicy | Agent pods mają deny-all egress; tylko IPC bridge łączy się z event busem |
+| **Policy-as-[[CRD - Custom Resource Definition\|CRD]]** | [[Admission Webhook]] | `SympoziumPolicy` gatuje narzędzia i sandboxe - enforcement at admission time |
+| **Memory-as-SQLite** | [[PersistentVolumeClaim\|PVC]] + sidecar | SQLite z FTS5 na PVC - semantic search, tagging, upgradeable do vector search |
+| **Schedule-as-CRD** | CronJob analogy | `SympoziumSchedule` definiuje recurring tasks z cron expressions |
+| **Skills-as-[[ConfigMap i Secret\|ConfigMap]]** | ConfigMap volume | SkillPacks generują ConfigMapy montowane w agent pods |
+| **Skill [[Sidecar Pattern\|sidecars]] z auto-[[RBAC]]** | Role/ClusterRole | [[Controller i Reconciler\|Controller]] auto-provisionuje efemeryczny RBAC per run |
+| **PersonaPacks** | Operator Bundle | Controller stampuje SympoziumInstances, Schedules i memory ConfigMaps |
+| **MCP servers as CRD** | [[Deployment]] + Service | MCPServer CRD zarządza lifecycle, probes tools, bridge translates protocol |
+| **Node probe [[DaemonSet]]** | DaemonSet | Odkrywa lokalne inference providers - annotuje nody |
+
+## Analiza filozofii architekturalnej
+
+### Ephemeral over Persistent
+
+Fundamentalna decyzja: **każde wywołanie agenta to nowy pod**. To odwrotność podejścia kagent/CrewAI/LangChain, gdzie agent żyje w długo działającym procesie.
+
+**Zalety:**
+- Blast-radius ograniczony do jednego poda
+- Natywne skalowanie horyzontalne
+- Automatyczne czyszczenie po zakończeniu
+- Każdy run ma własny [[SecurityContext]]
+
+**Wady:**
+- Cold-start per invocation (mitygowany przez warm pools)
+- Brak stanu w pamięci między runami (mitygowany przez persistent memory)
+
+### IPC przez system plików
+
+Agent nie komunikuje się bezpośrednio z control plane. Zamiast tego:
+
+```
+Agent → /ipc/*.json → fsnotify watcher → NATS → Controller
+```
+
+To podejście:
+- Eliminuje zależności sieciowe w kontenerze agenta
+- Jest language-agnostic (agent mógłby być w dowolnym języku)
+- Pozwala na prostą inspekcję (pliki JSON w woluminie)
+
+### Kubernetes jako framework, nie deployment target
+
+Sympozium nie "deployuje się na Kubernetes" - ono **jest Kubernetes**. Każdy koncept platformy mapuje się 1:1 na prymitywy K8s:
+
+- Agent → [[Job]]/[[Pod]]
+- Polityka → [[CRD - Custom Resource Definition|CRD]] + [[Admission Webhook]]
+- Skill → [[ConfigMap i Secret|ConfigMap]] + [[Sidecar Pattern|Sidecar]] + ephemeral [[RBAC]]
+- Schedule → CronJob-like CRD
+- Kanał → [[Deployment]]
+- Memory → [[PersistentVolumeClaim|PVC]] + SQLite
+
+---
+
+Powiązane: [[Czym jest Sympozium]] | [[Control Plane]] | [[Model bezpieczeństwa Defence-in-Depth]]
--- a/01-Przegląd/Struktura
+++ b/01-Przegląd/Struktura
@@ -0,0 +1,78 @@
+# Struktura repozytorium
+
+#sympozium #kod
+
+## Layout
+
+```
+sympozium/
+├── api/v1alpha1/           # Definicje typów CRD (Go)
+├── cmd/                    # Binaria
+│   ├── agent-runner/       # Agent w podzie (LLM loop + tool execution)
+│   ├── controller/         # Controller manager (wszystkie reconcilery)
+│   ├── apiserver/          # HTTP + WebSocket API server
+│   ├── ipc-bridge/         # IPC bridge sidecar (fsnotify → NATS)
+│   ├── memory-server/      # Memory sidecar (SQLite + FTS5)
+│   ├── web-proxy/          # Web proxy (OpenAI-compat + MCP gateway)
+│   ├── webhook/            # Admission webhook
+│   ├── node-probe/         # DaemonSet odkrywający inference providers
+│   └── sympozium/          # CLI + TUI (Bubble Tea)
+├── web/                    # Web dashboard (React + TypeScript + Vite)
+├── channels/               # Implementacje kanałów
+│   ├── telegram/
+│   ├── slack/
+│   ├── discord/
+│   └── whatsapp/
+├── internal/               # Pakiety wewnętrzne
+│   ├── controller/         # 6 reconcilerów + routery
+│   ├── orchestrator/       # PodBuilder & Spawner
+│   ├── apiserver/          # Handlery API
+│   ├── mcpbridge/          # MCP bridge sidecar
+│   ├── eventbus/           # NATS JetStream
+│   ├── ipc/                # IPC bridge
+│   ├── webhook/            # Enforcement polityk
+│   ├── webproxy/           # OpenAI proxy + MCP + rate limiting
+│   ├── session/            # Sesje (PostgreSQL)
+│   └── channel/            # Bazowe typy kanałów
+├── config/                 # Manifesty K8s
+│   ├── crd/bases/          # Wygenerowane CRD YAML
+│   ├── personas/           # Wbudowane PersonaPacks
+│   ├── skills/             # Wbudowane SkillPacks
+│   ├── policies/           # Presety SympoziumPolicy
+│   └── samples/            # Przykładowe CR
+├── charts/sympozium/       # Helm chart
+├── migrations/             # Migracje PostgreSQL
+├── test/integration/       # Testy integracyjne (shell)
+├── docs/                   # Dokumentacja
+└── images/                 # Dockerfiles
+```
+
+## Kluczowe pliki
+
+| Plik | Rola |
+|------|------|
+| `api/v1alpha1/*_types.go` | Definicje wszystkich CRD |
+| `internal/controller/agentrun_controller.go` | Serce systemu - reconciliation AgentRun → Job/Sandbox |
+| `internal/controller/sympoziuminstance_controller.go` | Zarządzanie instancjami, kanałami, memory |
+| `internal/orchestrator/podbuilder.go` | Budowanie spec'ów podów agentów |
+| `cmd/agent-runner/tools.go` | 7 wbudowanych narzędzi agenta |
+| `internal/eventbus/types.go` | Definicje tematów NATS |
+
+## Komponenty jako kontenery
+
+| Komponent | Obraz | Rola |
+|-----------|-------|------|
+| `controller` | Controller manager | Reconciluje wszystkie CRD |
+| `apiserver` | API server | HTTP + WebSocket + embedded web UI |
+| `agent-runner` | Agent | LLM provider agnostic runner |
+| `ipc-bridge` | Sidecar | fsnotify → NATS bridge |
+| `mcp-bridge` | Sidecar | MCP protocol translator |
+| `memory-server` | Sidecar/Deployment | SQLite + FTS5 |
+| `web-proxy` | Web proxy | OpenAI-compat API |
+| `webhook` | Admission webhook | Policy enforcement |
+| `node-probe` | DaemonSet | Inference discovery |
+| `channel-*` | Channel pods | Telegram, Slack, Discord, WhatsApp |
+
+---
+
+Powiązane: [[Czym jest Sympozium]] | [[Control Plane]]