toonic 1.0.6

Toonic — Universal TOON Format Platform for LLM-optimized file representations

🎵 Toonic — Universal TOON Format Platform

Token-Oriented Object Notation — kompaktowy format reprezentacji plików zoptymalizowany dla LLM.
Toonic Server dodaje dwukierunkowe strumieniowanie danych między źródłami (kod, logi, kamery RTSP) a modelami LLM z pełną historią wymiany danych.

---

📑 Spis treści

• Quick Start
• Architektura
• Toonic Server
• CLI Shell
• Web UI
• Docker
• RTSP Cameras
• Conversation History
• NLP/SQL Query
• LLM Router
• Przykłady
• API Reference
• Testing
• Dokumentacja
• Roadmap

---

🚀 Quick Start

# 1. Instalacja
git clone https://github.com/wronai/toonic.git
cd toonic
cp .env.example .env          # ← uzupełnij LLM_API_KEY
make install-all

# 2. Konwersja pliku do TOON
toonic spec ./main.py --format toon

# 3. Start serwera z Web UI
make server
# → http://localhost:8900

# 4. Analiza projektu z LLM
make server-code

# 5. Monitoring kamery RTSP
make server-camera

🏗 Architektura

Sources (watchers)  →  TOON Pipeline  →  Context Accumulator  →  LLM Router  →  Actions
     ↑                                     (token budget)            ↓
     └────────── feedback ←──── History DB ←──── ActionResponse ←── LLM
                                    ↓
                              NLP/SQL Query ← User

Komponent	Opis
FileWatcher	Monitoruje katalogi, konwertuje pliki do TOON
LogWatcher	Tail log files, kategoryzacja ERR/WARN/INFO
StreamWatcher	RTSP video, scene detection, keyframe extraction
Accumulator	Token budget management per kategoria
LLM Router	Routing do odpowiedniego modelu (text/code/multimodal)
History DB	SQLite log wszystkich wymian z LLM
NLP/SQL Adapter	Przeszukiwanie historii przez zapytania naturalne

→ Pełna dokumentacja: docs/architecture.md

🖥 Toonic Server

# Minimalny start
python -m toonic.server --source file:./src/ --goal "analyze code"

# Multi-source z kamerą
python -m toonic.server \
  --source file:./src/ \
  --source log:./logs/app.log \
  --source rtsp://admin:123456@192.168.188.146:554/h264Preview_01_main \
  --goal "code quality + log anomalies + video monitoring" \
  --interval 30

# Z konfiguracją YAML
python -m toonic.server --config toonic-server.yaml

→ Dokumentacja: docs/server.md

⚡ Trigger System — Event-Driven LLM Dispatch

Zamiast wysyłać dane co N sekund, definiuj kiedy dane mają trafić do LLM:

# NLP: natural language → YAML triggers automatycznie
python -m toonic.server \
  --source "rtsp://admin:123456@192.168.188.146:554/h264Preview_01_main" \
  --goal "describe what you see in each video frame" \
  --when "the object person will be detected for 1 second, if not send frame min. every 1 minute"

# YAML: plik z regułami triggerów
python -m toonic.server \
  --source "rtsp://cam1:554/stream" \
  --triggers examples/video-captioning/triggers.yaml

Wspierane event types:

Event	Opis	Przykład
motion	Ruch w klatce	--when "when motion detected"
scene_change	Duża zmiana sceny	--when "on scene change"
object	Obiekt: osoba, samochód	--when "person detected for 2s"
pattern	Regex w logach	--when "error occurs 5 times in 60s"
speech	Detekcja mowy	--when "speech detected"
anomaly	Odchylenie statystyczne	threshold z-score

Tryby: periodic (co N s), on_event (na zdarzenie), hybrid (zdarzenie + fallback periodic)

→ Dokumentacja: docs/triggers.md

💻 CLI Shell

python -m toonic.server.client
toonic> status                           # status serwera
toonic> analyze find security issues     # trigger analizy
toonic> add ./new-project/ code          # dodaj źródło
toonic> add rtsp://cam1:554/stream video # dodaj kamerę
toonic> convert ./main.py toon           # konwersja pliku
toonic> history 10                       # ostatnie 10 wymian z LLM
toonic> query "errors from last hour"    # NLP query na historii
toonic> model google/gemini-3-flash-preview  # zmiana modelu

→ Dokumentacja: docs/cli.md

🌐 Web UI

Start: make server → otwórz http://localhost:8900

Panel	Funkcja
Live Events	Real-time stream eventów z watcherów
LLM Actions	Odpowiedzi LLM z akcjami
Sources	Dynamiczne dodawanie/usuwanie źródeł
Stats	Tokeny, chunks, uptime, LLM calls
History	Przeglądanie historii wymian z LLM
Query	NLP/SQL wyszukiwanie w metadanych

→ Dokumentacja: docs/web-ui.md

🐳 Docker

# Pełny stack: RTSP test streams + Toonic Server
cd docker/
cp ../.env.example ../.env    # uzupełnij LLM_API_KEY
docker compose up -d

# Tylko test streams (bez serwera)
make docker-streams

# Logi
make docker-logs

Test streams w Docker:

• rtsp://localhost:8554/test-cam1 — 640×480 test pattern + audio
• rtsp://localhost:8554/test-cam2 — 320×240 SMPTE bars
• rtsp://localhost:8554/test-audio — audio-only sine wave

→ Dokumentacja: docs/docker.md

📹 RTSP Cameras

# Real camera
python -m toonic.server \
  --source "rtsp://admin:123456@192.168.188.146:554/h264Preview_01_main" \
  --goal "security monitoring: detect movement" \
  --interval 10

# Multiple cameras
python -m toonic.server \
  --source "rtsp://admin:pass@cam1:554/stream" \
  --source "rtsp://admin:pass@cam2:554/stream" \
  --goal "multi-camera monitoring"

StreamWatcher automatycznie:

• Łączy się z RTSP przez OpenCV
• Wykrywa zmiany sceny (scene detection, threshold 0.4)
• Wysyła keyframes jako base64 JPEG (160×120, Q=10, ~2.5kB)
• Bez OpenCV → mock mode do testowania pipeline

📜 Conversation History

Każda wymiana z LLM jest zapisywana w SQLite z pełnymi metadanymi:

# Programmatic access
from toonic.server.core.history import ConversationHistory

history = ConversationHistory("./toonic_history.db")
records = history.search(category="video", since="1h")
for r in records:
    print(f"[{r.timestamp}] {r.model} → {r.action_type}: {r.content[:100]}")

# CLI
toonic> history 20                      # last 20 exchanges
toonic> history --category video        # only video-related
toonic> history --model gemini          # only gemini model
toonic> history --action code_fix       # only code fixes

→ Dokumentacja: docs/history.md

🔍 NLP/SQL Query

Przeszukuj historię wymian z LLM za pomocą zapytań naturalnych lub SQL:

# NLP queries (przekształcane na SQL przez LLM)
toonic> query "show all errors from the last hour"
toonic> query "which files were fixed today?"
toonic> query "camera events with high confidence"

# Direct SQL
toonic> sql SELECT * FROM exchanges WHERE category='video' ORDER BY timestamp DESC LIMIT 10

→ Dokumentacja: docs/query.md

🔀 LLM Router

Router automatycznie kieruje zapytania do odpowiedniego modelu:

Kategoria	Model	Routing
code, config, database	code model	Gemini / Claude
logs, document, data	text model	Gemini Flash
video, audio	multimodal model	Gemini / GPT-4o

Konfiguracja w .env:

LLM_API_KEY=sk-or-v1-...
LLM_MODEL=google/gemini-3-flash-preview

Lub w toonic-server.yaml:

models:
  text:
    model: google/gemini-3-flash-preview
  code:
    model: google/gemini-3-flash-preview
  multimodal:
    model: google/gemini-3-flash-preview
    supports: [text, image, audio]

📂 Przykłady

Przykład	Opis	Start
code-analysis	Analiza kodu, wykrywanie bugów	make server-code
log-monitoring	Real-time monitoring logów	make server-logs
video-monitoring	RTSP camera monitoring	make server-camera
multi-source	Kod + logi + RTSP combined	make server-multi
video-captioning	Video captioning z LLM	README
security-audit	Audyt bezpieczeństwa kodu	README

📡 API Reference

Endpoint	Method	Opis
/	GET	Web UI
/ws	WS	WebSocket — live events
/api/status	GET	Server status
/api/actions	GET	Recent LLM actions
/api/analyze	POST	Trigger analysis
/api/sources	POST	Add data source
/api/sources/{id}	DELETE	Remove source
/api/convert	POST	Convert file to TOON
/api/formats	GET	List supported formats
/api/history	GET	Conversation history
/api/query	POST	NLP/SQL query on history

→ Pełna dokumentacja: docs/api.md

🧪 Testing

make test            # All tests (160+)
make test-server     # Server tests only
make test-cov        # With coverage report

📖 Dokumentacja

• docs/architecture.md — Architektura systemu
• docs/server.md — Toonic Server
• docs/cli.md — CLI Shell
• docs/web-ui.md — Web UI
• docs/docker.md — Docker setup
• docs/api.md — REST API reference
• docs/history.md — Conversation History
• docs/query.md — NLP/SQL Query
• docs/triggers.md — Trigger System (event-driven dispatch)
• docs/plugins.md — Plugin system (watchers)
• TODO/12-toonic-server-architecture.md — Architecture proposal

🗺 Roadmap

• TOON format — 14 file type handlers
• Pipeline — spec / reproduce / batch
• Evidence Graph — cross-reference analysis
• Server — watchers + accumulator + LLM router
• Web UI — real-time events + stats
• Docker — RTSP test streams
• Conversation History — SQLite logging
• NLP/SQL Query — search history
• Trigger System — event-driven LLM dispatch (YAML DSL + NLP2YAML)
• Event Detectors — motion, scene_change, object, pattern, anomaly, speech
• gRPC transport (Phase 3)
• MCP Streamable HTTP bridge
• Rust port (tonic + prost)
• Audio VAD watcher (webrtcvad)
• Git diff watcher
• Plugin marketplace

📄 License

Apache-2.0 — see LICENSE

Created by Tom Sapletta — [e-mail]

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - [e-mail]