ARGUS Native Plugins for TuGraph

Repozytorium zawiera dwie natywne procedury C++17 dla TuGraph Community 4.5.2:

• argus_linker — wyprowadza ukryte relacje z powtarzalnej, rzadkiej współobecności osób;
• argus_risk — analizuje konflikt relacyjny, ścieżki do pięciu stopni, współobecność, trójkąty intymność–konflikt, presję sieciową i odchylenie od rutyny.

To jest samodzielna warstwa TuGraph, a nie pełny projekt ARGUS. Repozytorium nie zawiera panelu WWW, importera produkcyjnego, SQLite ani kodu publikującego sprawy. Zawiera natomiast zamknięty, odtwarzalny snapshot syntetycznego społeczeństwa z pełnej doby 2026-08-31. Służy on wyłącznie do walidacji modelu grafu i obu procedur na strumieniu o realistycznej strukturze.

Kod jest udostępniany na licencji MIT.

Obsługiwana platforma

Referencyjne środowisko:

• Ubuntu 22.04;
• TuGraph Community 4.5.2;
• Docker Engine 29 lub zgodny;
• Bash 4.4+, PHP 8.1 z rozszerzeniem cURL, curl i sha256sum;
• C++17, kompilowany w obrazie tugraph/tugraph-compile-centos7:1.3.5.

Plugin C++ jest związany z ABI TuGraph. Nie należy instalować biblioteki skompilowanej przeciw innej wersji nagłówków lub liblgraph.so. Skrypt budujący kopiuje SDK bezpośrednio z obrazu runtime albo ze wskazanego kontenera, dzięki czemu kompilator i uruchomiona baza używają tego samego interfejsu.

Struktura repozytorium

.
├── src/
│   ├── argus_linker.cpp
│   └── argus_risk.cpp
├── schema/
│   └── argus-v2.cypher
├── dataset/2026-08-31/
│   ├── manifest.json
│   ├── import.json
│   └── *.csv.gz
├── scripts/
│   ├── tugraph-api.php
│   ├── docker-manual/       # Docker uruchamiany przez zwykłego użytkownika
│   ├── systemd-native/      # systemd uruchamia bezpośrednio lgraph_server
│   ├── systemd-docker/      # systemd zarządza kontenerem
│   ├── dataset/             # import, walidacja i test snapshotu
│   ├── dev/                 # build, wdrożenie i smoke testy
│   └── lib/                 # wspólne wnętrze skryptów
├── config/
│   ├── tugraph.env.example
│   └── tugraph-systemd.env.example
├── systemd/
│   ├── argus-tugraph-docker.service.in
│   └── argus-tugraph-native.service.in
├── Makefile
└── LICENSE

build/, dist/ i var/ są artefaktami lokalnymi i nie trafiają do Git.

Szybki start w Dockerze

Skopiuj konfigurację, ustaw własne hasło i pozostaw porty związane z localhostem:

cp config/tugraph.env.example config/tugraph.env
${EDITOR:-vi} config/tugraph.env
scripts/dev/check.sh
scripts/docker-manual/up.sh --pull
scripts/dev/build.sh
scripts/dev/init-schema.sh
scripts/dev/install-plugins.sh
scripts/docker-manual/status.sh

Te same operacje są dostępne jako make check, make up, make build, make schema, make install i make status.

Domyślne endpointy:

Usługa	Adres hosta
HTTP/Browser	http://127.0.0.1:7070/
Bolt	127.0.0.1:7687
RPC	127.0.0.1:9090

Dane LMDB i logi są montowane z var/tugraph/, więc usunięcie lub odtworzenie kontenera nie usuwa grafu. Zwykłe uruchomienie jest idempotentne: istniejący kontener zostaje uruchomiony ponownie. Dopiero --recreate zastępuje kontener, nadal bez kasowania katalogu danych.

scripts/docker-manual/down.sh
scripts/docker-manual/up.sh

# Zmiana obrazu, portów lub flag wymaga jawnego odtworzenia kontenera:
scripts/docker-manual/up.sh --pull --recreate

TUGRAPH_ENABLE_PLUGIN=1 pozwala dodawać i usuwać procedury. Po zakończeniu wdrożenia można ustawić wartość 0 i odtworzyć proces TuGraph. Zainstalowane procedury nadal są przechowywane przez bazę, natomiast administracyjny upload i delete zostają zablokowane.

Konfiguracja

Każde polecenie wymaga czterech ustawień połączenia. Muszą być przekazane jako zmienne środowiskowe albo znajdować się w czytelnym config/tugraph.env. Zmienne procesu mają pierwszeństwo przed plikiem. Brak ustawienia kończy działanie jawnym błędem — klient nie zgaduje loginu, hasła, grafu ani endpointu.

Zmienna	Wymaganie / wartość domyślna	Znaczenie
TUGRAPH_URL	wymagane	REST API, np. http://127.0.0.1:7070
TUGRAPH_USER	wymagane	użytkownik administracyjny
TUGRAPH_PASSWORD	wymagane	hasło; brak wartości w repozytorium
TUGRAPH_GRAPH	wymagane	nazwa grafu
TUGRAPH_RUNTIME_IMAGE	runtime 4.5.2	obraz bazy i źródło SDK
TUGRAPH_COMPILER_IMAGE	compile 1.3.5	obraz kompilatora ABI
TUGRAPH_CONTAINER	argus-tugraph	nazwa kontenera
TUGRAPH_BIND_HOST	127.0.0.1	adres publikacji portów
TUGRAPH_DATA_DIR	var/tugraph/data	trwałe dane LMDB
TUGRAPH_LOG_DIR	var/tugraph/log	trwałe logi

Pliki przykładowe zawierają wyłącznie CHANGE_ME. Nie wolno publikować portu 7070 poza zaufanym interfejsem przed ustawieniem własnego hasła i wdrożeniem właściwej kontroli dostępu. config/tugraph.env jest ignorowany przez Git.

Kompilacja

Pełny build:

scripts/dev/build.sh

Tylko jedna procedura:

scripts/dev/build.sh --plugin argus_linker
scripts/dev/build.sh --plugin argus_risk

Domyślnie skrypt tworzy tymczasowy, nieuruchomiony kontener z obrazu TuGraph i kopiuje z niego /usr/local/include oraz liblgraph.so. Jeżeli właściwe SDK ma pochodzić z już działającej instancji:

scripts/dev/build.sh --runtime-container argus-tugraph

Wyniki:

dist/argus_linker.so
dist/argus_risk.so

Po każdej kompilacji wypisywany jest SHA-256 artefaktu. Do publicznego release warto dołączyć sumy, dokładne referencje obrazów wraz z digestami i wynik builda na czystym Ubuntu 22.04.

Schemat wymagany przez pluginy

schema/argus-v2.cypher zawiera minimalny model potrzebny obu procedurom. scripts/dev/init-schema.sh wysyła każde polecenie oddzielnie i traktuje odpowiedź „already exists” jako sukces, dzięki czemu może zostać bezpiecznie powtórzony.

Wierzchołki

Citizen przechowuje stabilny person_id oraz bieżący przedział stanu:

• current_building, current_unit;
• state_since, state_until;
• name, first_seen, last_seen i opis bieżącej aktywności.

Observation jest niezmiennym faktem źródłowym identyfikowanym przez globalny seq. Dla rekonstrukcji rutyny wymagane są t_start, weekday (1–7) i time_slot (0–47, półgodzinne przedziały UTC).

Place jest identyfikowany przez rzeczywisty building_id. Brak miejsca nie powinien tworzyć wierzchołka Place(0), ponieważ stałby się superwęzłem łączącym wszystkie obserwacje bez lokalizacji.

Krawędzie

Citizen -[:HAS_OBSERVATION]-> Observation -[:OBSERVED_AT]-> Place
Citizen -[:RELATES_TO]-> Citizen
Citizen -[:ASSOCIATED_WITH]-> Citizen

• RELATES_TO jest jawnym, temporalnym stanem pary. Powinno być zapisywane kanonicznie od niższego do wyższego person_id.
• ASSOCIATED_WITH jest inference tworzoną przez argus_linker. Plugin zapisuje ją w odwrotnym kierunku kanonicznym, aby oba rodzaje wiedzy pozostały osobno.
• argus_risk traktuje oba rodzaje relacji jako nieskierowane semantycznie i czyta incoming oraz outgoing adjacency.

Indeks Citizen.current_building jest wymagany dla szybkiego utworzenia listy kandydatów współobecności. Indeks pair-unique po ASSOCIATED_WITH.pair_key zapewnia idempotentny upsert linkera.

Jeżeli istniejący projekt ma szerszy schemat tych samych etykiet, nie należy bezrefleksyjnie wykonywać pliku inicjalizacyjnego. Trzeba porównać typy i pola; pluginy tolerują dodatkowe properties, ale wymagają zgodności pól odczytywanych przez kod.

Instalacja i aktualizacja pluginów

TuGraph musi działać z --enable_plugin 1. Następnie:

scripts/dev/install-plugins.sh

# Kompilacja i instalacja jednym poleceniem:
scripts/dev/install-plugins.sh --build

# Tylko jedna procedura:
scripts/dev/install-plugins.sh --plugin argus_risk

Samodzielny klient PHP loguje się do /login, pobiera JWT, usuwa poprzednią wersję pluginu o tej samej nazwie i wysyła .so do endpointu cpp_plugin. Nie wymaga Composera ani kodu ARGUS. Uprawnienia są ustawiane zgodnie z zachowaniem kodu:

Plugin	Tryb TuGraph	Powód
argus_linker	read-write	zapisuje ASSOCIATED_WITH
argus_risk	read-only	wyłącznie analizuje i zwraca JSON

Aktualizacja ma krótkie okno między delete i ponownym uploadem. System wywołujący powinien na ten czas zatrzymać nowe analizy albo traktować brak procedury jako błąd ponawialny. Nie wolno uruchamiać zastępczego scoringu o innej semantyce.

Usunięcie obu pluginów bez naruszania grafu:

scripts/dev/uninstall-plugins.sh

argus_linker

Procedura read-write rekonstruuje relacje z topologii obserwacji. Grupuje osoby według wierzchołka Place i krótkiego okna czasu, deduplikuje uczestników, odrzuca tłum, a następnie materializuje pary widziane w co najmniej dwóch niezależnych kubełkach.

Przykład:

scripts/dev/call-plugin.sh argus_linker '{
  "bucket_seconds": 120,
  "min_encounters": 2,
  "max_bucket_people": 6,
  "max_edges": 250000
}' 60

Parametry:

Pole	Domyślnie	Dozwolony zakres	Znaczenie
bucket_seconds	120	30–600	szerokość okna czasu
min_encounters	2	2–20	minimalna liczba niezależnych okien
max_bucket_people	6	2–20	próg odrzucenia tłumu
max_edges	250000	1000–1000000	limit najsilniejszych relacji
from_at	min INT64	—	początek czasu źródłowego
to_at	max INT64	—	koniec czasu źródłowego

Wynik zawiera m.in. liczbę obserwacji, zbadanych krawędzi, zaakceptowanych i zatłoczonych kubełków, par kandydackich, par zakwalifikowanych, insertów, aktualizacji oraz czas procedury. Ponowne wywołanie na tym samym grafie powinno aktualizować istniejące krawędzie, a nie tworzyć duplikaty.

argus_risk

Procedura read-only działa w dwóch trybach.

Skan osoby przeciw aktualnie współobecnym kandydatom:

scripts/dev/call-plugin.sh argus_risk \
  '{"person_id":12,"at":1788019200,"budget_ms":1500}'

Analiza konkretnej pary, zwracająca także wynik qualified=false:

scripts/dev/call-plugin.sh argus_risk \
  '{"person_id":12,"person_b":34,"at":1788019200,"threshold":55}'

Parametry:

Pole	Domyślnie	Zakres	Znaczenie
person_id	wymagane	INT64	osoba początkowa
person_b	brak	INT64	opcjonalna druga osoba
at	aktualny epoch	INT64	chwila analizy
max_depth	5	1–5	maksymalna długość simple path
max_visited	10000	50–100000	budżet odwiedzonych stanów
max_candidates	80	1–500	limit współobecnych osób
max_observations	600	20–5000	historia rutyny na osobę
threshold	55	1–100	globalny próg kwalifikacji
budget_ms	1500	50–10000	deadline całego requestu

Każda sprawa zawiera:

• algorithm=argus-graph-v2 i rodzaj sprawy;
• końcowy risk oraz wszystkie komponenty;
• potwierdzenie budynku, lokalu i nakładania przedziałów;
• wybraną ścieżkę z osobami i właściwościami każdej krawędzi;
• wykryty trójkąt intymność–konflikt;
• próbkę, prawdopodobieństwo i ufność rekonstrukcji rutyny;
• stabilne reason_codes;
• regułę kwalifikacji (global_threshold albo network_convergence).

Odpowiedź główna zwraca również visited_vertices, examined_edges, examined_observations, procedure_ms i truncated. truncated=true oznacza, że zadziałał limit — brak dodatkowej ścieżki nie jest wtedy dowodem jej nieistnienia.

Plugin nie tworzy RiskCase. Trwałe zapisanie odpowiedzi, jej wersjonowanie i połączenie z materiałem dowodowym są obowiązkiem aplikacji wywołującej.

Dataset 2026-08-31 i test funkcjonalny

Snapshot obejmuje półotwarty przedział 2026-08-31T00:00:00Z..2026-09-01T00:00:00Z oraz sekwencje 294835001..295985402. Są to stare dane i właśnie dlatego nadają się do testu: pluginy przyjmują from_at, to_at i at, więc wynik zależy od jawnie podanego czasu analizy, a nie od zegara maszyny uruchamiającej test.

Zawartość zatwierdzonego snapshotu:

Element grafu	Liczba
Observation	1 150 402
HAS_OBSERVATION	1 208 487
OBSERVED_AT	1 136 414
Citizen	109 364
Place	1 572
RELATES_TO	29 253

To nie jest losowanie wykonane na potrzeby repozytorium. Eksport pochodzi z działającej instancji, która wcześniej przyjęła strumień generatora społeczeństwa. W snapshotcie zachowano fakty i ich topologię. Bieżący stan Citizen odtworzono z ostatniej obserwacji tej osoby w badanej dobie, a RELATES_TO — wyłącznie ze zdarzeń należących do przedziału, z 14-dniowym zanikiem temperatur. Zapobiega to przeciekowi wiedzy z dni następujących po badanym okresie.

ASSOCIATED_WITH celowo nie ma danych wejściowych. Ta krawędź jest wynikiem argus_linker; dołączenie jej do eksportu zamieniłoby test algorytmu w test odczytu gotowej odpowiedzi.

Kontrola pobranych archiwów nie łączy się z bazą:

scripts/dataset/verify.php

Sam import offline tworzy bazę w var/dataset-test/data i nie uruchamia serwera. Odmawia nadpisania istniejącego katalogu, dopóki nie podano --force:

scripts/dataset/import.sh
scripts/dataset/import.sh --force

Pełny test jest jednym poleceniem. Weryfikuje SHA-256, rozpakowuje pliki, wykonuje import offline, kompiluje pluginy, uruchamia osobny kontener na portach 17070/17687/19090, zakłada indeksy, instaluje procedury i sprawdza liczniki, wynik linkera, jego idempotencję oraz analizę pary przez argus_risk:

scripts/dataset/test.sh --force

Kontener testowy nazywa się argus-tugraph-dataset-test. Po teście kontener, rozpakowane CSV i testowe LMDB są usuwane; baza produkcyjna, jej kontener i var/tugraph nie są używane. Opcja --keep pozostawia testową instancję do ręcznych eksperymentów. Nazwy, porty i katalog roboczy można zmienić przez zmienne ARGUS_DATASET_* opisane w skrypcie. Pozostawione artefakty usuwa scripts/dataset/clean.sh; cleaner wymaga własnego pliku znacznika i odmawia usunięcia katalogu zamontowanego przez działający kontener.

Smoke test

Po wgraniu własnych danych podaj istniejący person_id:

ARGUS_TEST_PERSON_ID=12 ARGUS_TEST_AT=1788019200 scripts/dev/smoke-test.sh

Test sprawdza, czy oba endpointy odpowiadają oczekiwaną nazwą algorytmu. Nie zastępuje testów domenowych na golden graph z kontrolowanymi ścieżkami 3-hop i 5-hop.

systemd

Repozytorium zawiera dwa szablony. Oba instalują tę samą nazwę jednostki argus-tugraph.service, dlatego wybiera się jeden tryb.

systemd zarządzający kontenerem

Umieść checkout w trwałej lokalizacji, np. /opt/argus-tugraph-plugins, a potem:

sudo scripts/systemd-docker/install.sh
sudoedit /etc/argus-tugraph/tugraph.env
sudo systemctl enable --now argus-tugraph.service

W konfiguracji systemowej TUGRAPH_DOCKER_RESTART=no, ponieważ cyklem życia kontenera zarządza systemd, a nie równolegle polityka restartu Dockera.

Natywny lgraph_server jako systemd

Ten wariant nie instaluje binariów TuGraph. Najpierw należy umieścić zgodne TuGraph 4.5.2 oraz zasoby Browsera w ścieżkach wskazanych przez konfigurację.

sudo scripts/systemd-native/install.sh
sudoedit /etc/argus-tugraph/tugraph.env
sudo scripts/systemd-native/install.sh --enable-now

Instalator tworzy systemowego użytkownika argus-tugraph, katalog danych, katalog logów i jednostkę z podstawowym hardeningiem. Domyślnie serwer natywny nasłuchuje wyłącznie na 127.0.0.1.

--enable-now jest celowo opcjonalne: instalacja pliku usługi nie powinna samoczynnie uruchamiać bazy przed sprawdzeniem hasła, ścieżek i praw dostępu.

Operacje i bezpieczeństwo

• Nie uruchamiaj dwóch procesów TuGraph na tym samym katalogu LMDB.
• Nie kopiuj aktywnego katalogu danych zwykłym cp; używaj mechanizmu backupu zgodnego z wersją TuGraph i wykonuj test odtworzenia.
• Przed aktualizacją TuGraph przebuduj pluginy przeciw nowemu SDK i uruchom golden tests. Zgodność nazwy funkcji Process nie gwarantuje zgodności ABI.
• Trzymaj HTTP, Bolt i RPC na localhost lub w wydzielonej sieci. Publiczna aplikacja powinna udostępniać zamknięte endpointy domenowe, nie dowolny Cypher.
• Monitoruj czas procedur, truncated, liczbę odwiedzonych krawędzi, rozmiar LMDB, opóźnienie dysku i nowe superwęzły.
• argus_linker modyfikuje graf. Uruchamiaj go kontem i procedurą operacyjną inną niż interaktywne zapytania analityka.
• Nie wprowadzaj wyniku argus_risk z powrotem jako Observation ani RELATES_TO. Alert nie może stać się dowodem kolejnego alertu.