🎵 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
Trigger System
Data Directory
CLI Shell
Web UI
Docker
RTSP Cameras
Conversation History
NLP/SQL Query
LLM Router
Przykłady
API Reference
Testing
Dokumentacja
Roadmap

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

5. Monitoring kamery RTSP

make server-camera


## 🏗 Architektura

Sources (watchers) → TOON Pipeline → Context Accumulator → LLM Router → Actions ↑ ↓ (token budget) ↓ │ Trigger Scheduler ↓ │ (event detectors) ↓ └────────── feedback ←──── History DB ←──── ActionResponse ←────── LLM ↓ NLP/SQL Query ← User Data Directory (JSONL logs)


| Komponent | Opis |
|-----------|------|
| **FileWatcher** | Monitoruje katalogi, konwertuje pliki do TOON |
| **LogWatcher** | Tail log files, kategoryzacja ERR/WARN/INFO |
| **StreamWatcher** | RTSP video, scene detection, keyframe extraction |
| **HttpWatcher** | Monitoring stron WWW, API, health endpoints, SSL, content changes |
| **ProcessWatcher** | Monitoring procesów, portów TCP, usług systemowych |
| **DirectoryWatcher** | Detekcja zmian struktury katalogów (nowe/usunięte/przeniesione pliki) |
| **DockerWatcher** | Monitoring kontenerów Docker (status, zasoby, logi) |
| **DatabaseWatcher** | Monitoring baz danych — schema changes, row counts, custom SQL queries |
| **NetworkWatcher** | Monitoring sieci — ping, DNS, TCP ports, latency |
| **TriggerScheduler** | Event-driven dispatch: periodic/on_event/hybrid modes |
| **Event Detectors** | Motion, scene_change, object, pattern, speech, anomaly |
| **Accumulator** | Token budget management per kategoria |
| **LLM Router** | Routing do odpowiedniego modelu (text/code/multimodal) |
| **History DB** | SQLite log wszystkich wymian z LLM |
| **Data Directory** | JSONL logs: events, exchanges, server logs |
| **NLP/SQL Adapter** | Przeszukiwanie historii przez zapytania naturalne |

→ Pełna dokumentacja: [docs/architecture.md](docs/architecture.md)

# 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

# Monitoring WWW + API
python -m toonic.server \
  --source http://example.com \
  --source http://api.example.com/health \
  --goal "monitor website availability and content changes"

# Monitoring procesów i usług
python -m toonic.server \
  --source proc:nginx \
  --source port:5432 \
  --source service:postgresql \
  --goal "monitor service health"

# Monitoring Docker + baza danych
python -m toonic.server \
  --source docker:* \
  --source db:production.db \
  --goal "monitor containers and database changes"

# Monitoring sieci
python -m toonic.server \
  --source net:8.8.8.8,1.1.1.1 \
  --source tcp:db-server:5432 \
  --goal "network connectivity monitoring"

# Monitoring struktury katalogów
python -m toonic.server \
  --source dir:/var/data/uploads \
  --goal "detect new files and structural changes"

# 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 if exist min 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)

Generated triggers.yaml zapisywany automatycznie w CWD:

triggers:
  - name: object-person-hybrid
    mode: hybrid
    interval_s: 60.0
    source: video
    events:
      - type: object
        threshold: 0.3
        min_duration_s: 1.0
        label: person
    fallback:
      periodic_s: 60.0
    cooldown_s: 1.0
    goal: describe what you see in each video frame

→ Dokumentacja: docs/triggers.md

📁 Data Directory — Persistent Logging

Wszystkie dane serwera zapisywane w toonic_data/ (lub $TOONIC_DATA_DIR):

toonic_data/
├── events.jsonl          # Wszystkie eventy (context, trigger, action, status)
├── exchanges.jsonl       # LLM exchanges (subset of events)
├── history.db            # SQLite z pełną historią wymian
├── server.log            # Server logs (duplikat konsoli)
└── sources/              # Cached source data

Przykład events.jsonl:

{"event":"context","data":{"source_id":"video:rtsp://...","category":"video","toon_spec":"..."},"timestamp":1772108742.92}
{"event":"trigger","data":{"rule":"object-person-hybrid","reason":"periodic","detections":[]},"timestamp":1772108742.92}
{"event":"action","data":{"action_type":"report","content":"The frame shows...","model_used":"google/gemini-3-flash-preview"},"timestamp":1772108749.22}

Browsing via API:

curl http://localhost:8900/api/events?limit=50
curl http://localhost:8900/api/data-dir

💻 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

Nowy tabbed layout z 6 zakładkami:

Tab	Funkcja
Events	Live event stream (context, trigger, action, error) z filtrowaniem
LLM Actions	Przeglądarka wymian z LLM (expandable, metadata)
History	SQLite conversation history + NLP query interface
Triggers	Trigger rules config + runtime stats
Sources	Active sources + dynamiczne dodawanie/usuwanie
Overview	Server stats: chunks, actions, events, tokens, uptime

Features:

WebSocket live updates
Event filtering (all/context/trigger/action/status/error)
Click to expand events/exchanges
NLP query: "errors from last hour" → SQL → results
Trigger stats: event_count, periodic_count, last_triggered

→ Dokumentacja: docs/web-ui.md

Pełny stack: RTSP test streams + Toonic Server

cd docker/ cp ../.env.example ../.env # uzupełnij LLM_API_KEY docker compose up -d

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](docs/docker.md)

# 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 (tabbed layout)
`/ws`	WS	WebSocket — live events
`/api/status`	GET	Server status + trigger stats
`/api/events`	GET	Event log (limit, event_type filter)
`/api/triggers`	GET	Trigger config + runtime stats
`/api/data-dir`	GET	List files in data directory
`/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 (filters: category, model, action_type)
`/api/history/stats`	GET	History statistics
`/api/query`	POST	NLP query on history
`/api/sql`	POST	Direct SQL query on history

→ Pełna dokumentacja: docs/api.md

🧪 Testing

make test            # All tests (227 passed)
make test-server     # Server tests only
make test-triggers   # Trigger system tests
make test-watchers   # Watcher tests (9 types)
make test-cov        # With coverage report

Test coverage:

Core pipeline: 14 file handlers
Server: watchers (9 types), accumulator, router, history
Watchers: File, Log, Stream, HTTP, Process, Directory, Docker, Database, Network
Triggers: DSL, detectors (7 types), scheduler (3 modes), NLP2YAML
Web UI: REST API, WebSocket, event broadcasting

📖 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

📄 License

Apache-2.0 — see LICENSE

Created by Tom Sapletta — tom@sapletta.com

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - tom@sapletta.com

Status

Last updated by taskill at 2026-04-25 13:48 UTC

Metric	Value
HEAD	`191f17d`
Coverage	—
Failing tests	—
Commits in last cycle	33

Introduced a CLI interface for toonic with supporting modules, added a deep code analysis engine and a configuration management system, and applied related docs/tests improvements and refactors.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🎵 Toonic — Universal TOON Format Platform

📑 Spis treści

1. Instalacja

2. Konwersja pliku do TOON

5. Monitoring kamery RTSP

⚡ Trigger System — Event-Driven LLM Dispatch

📁 Data Directory — Persistent Logging

💻 CLI Shell

🌐 Web UI

Pełny stack: RTSP test streams + Toonic Server

Logi

📜 Conversation History

🔍 NLP/SQL Query

🔀 LLM Router

📂 Przykłady

📡 API Reference

🧪 Testing

📖 Dokumentacja

🗺 Roadmap

📄 License

License

Author

Status

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🎵 Toonic — Universal TOON Format Platform

📑 Spis treści

1. Instalacja

2. Konwersja pliku do TOON

5. Monitoring kamery RTSP

⚡ Trigger System — Event-Driven LLM Dispatch

📁 Data Directory — Persistent Logging

💻 CLI Shell

🌐 Web UI

Pełny stack: RTSP test streams + Toonic Server

Logi

📜 Conversation History

🔍 NLP/SQL Query

🔀 LLM Router

📂 Przykłady

📡 API Reference

🧪 Testing

📖 Dokumentacja

🗺 Roadmap

📄 License

License

Author

Status