sciveo 0.2.48

No project description provided

SCIVEO

Sciveo is a Python toolkit and CLI for ML/AI workflows, engineering automation, experiment tracking, machine monitoring, local operations, network/industrial IO, media processing, AI agents, local storage, and production ML inference.

It is meant for practical systems where models, data, devices, services, and operators meet: train or evaluate ML models, collect measurements, process media, monitor machines, communicate with edge or plant equipment, run agents, and keep the operational tooling close to the Python code that uses it.

The package is intentionally broad. The CLI is the easiest entry point for operations and lab work, while the Python modules expose the same building blocks for notebooks, services, experiments, and pipelines.

ML/AI and Engineering Focus

Sciveo is built around the common shape of applied ML, AI, and engineering work:

• define and run parameterized experiments;
• sample parameter spaces and record configurations;
• attach datasets, metrics, scores, plots, media, and generated artifacts;
• monitor machines that produce data or run services;
• communicate with lab, plant, edge, and networked devices;
• capture and process image/video/audio data;
• run local or remote ML inference close to the data;
• coordinate AI agents and local tools;
• synchronize results to an API-backed project when remote tracking is needed.

The operations modules are part of the same picture. Monitoring, network IO, local storage, media workers, and admin tooling are there because real ML and engineering deployments often include cameras, sensors, edge boxes, industrial controllers, GPU machines, local disks, APIs, and long-running background jobs.

Main Capabilities

• Monitoring and watchdogs: host metrics, GPU/server telemetry where available, plant/Modbus monitoring, local watchdog actions, and service installation helpers.
• Experiments and project helpers: project runs, parameter sampling, datasets, scores, plots, metadata, and optional remote synchronization.
• Network and industrial IO: network discovery, SSH inventory/execution, Modbus TCP/RTU reads and writes, SNMP, MQTT, HTTP helpers, and protocol emulators.
• Admin and diagnostics: first-boot edge administration, Wi-Fi access point provisioning, service checks, doctor reports, and fleet inventory.
• Media capture and processing: RTSP/NVR capture, screen/camera capture, local media processing, ML media processors, and queue/API-backed media workers.
• AI agent console: interactive and one-shot agent workflows with hosted providers, local tools, image inputs, and optional local Hugging Face/GGUF runtimes.
• Encrypted chat rooms: shared-token chat rooms for lightweight operator and agent coordination.
• Local S3-compatible storage: a boto3-compatible object store backed by mounted local paths.
• SCIVEYOLO inference: Sciveo-owned SCIVEYOLO inference artifacts and runtime for production object detection without requiring Ultralytics at runtime.
• Supporting API, DB, web, content, and tools modules: shared building blocks used by experiments, services, and pipeline jobs.

Typical Workflows

Sciveo is useful when a project needs more than one isolated script. The common pattern is a Python workflow that touches models, measurements, local services, devices, and result tracking.

ML/AI Workflow

Use Sciveo to keep model work reproducible and close to the runtime environment:

import sciveo

def train_one_run():
    with sciveo.open() as experiment:
        learning_rate = experiment.config.learning_rate
        batch_size = experiment.config.batch_size

        metrics = {
            "loss": 0.18,
            "accuracy": 0.94,
        }

        experiment.log({"learning_rate": learning_rate, "batch_size": batch_size})
        experiment.eval("loss", metrics["loss"])
        experiment.eval("accuracy", metrics["accuracy"])
        experiment.score(metrics["accuracy"])

sciveo.start(
    project="vision-model-eval",
    function=train_one_run,
    configuration={
        "learning_rate": {"values": [0.001, 0.0005]},
        "batch_size": {"values": [8, 16]},
    },
    remote=False,
    count=4,
)

Engineering and Edge Workflow

Use the CLI to inspect and operate machines that produce data or run inference:

sciveo doctor --render json
sciveo scan --net 192.168.10.0/24 --health
sciveo fleet --net 192.168.10.0/24 --users operator,admin -i ~/.ssh/id_ed25519 --render json
sciveo monitor --period 60
sciveo watchdog --src memory --threshold 90 --period 10 --execute "systemctl restart app"

Media and Inference Workflow

Use media commands for local processing, and .sciveyolo artifacts for production object detection without requiring Ultralytics at runtime:

sciveo rtsp --url rtsp://camera/stream --output-path ./clip.mp4
sciveo media-run --input-path ./clip.mp4 --output-path ./media-out --render text
sciveo media-run --mode ml --processor image-object-detection --input-path ./frame.jpg --output-path ./detections

from sciveo.ml.images.sciveyolo import SCIVEYOLO

model = SCIVEYOLO("detector.sciveyolo")
results = model.predict("frame.jpg")

Device and Protocol Workflow

Use network and industrial IO helpers directly from the CLI during bring-up, testing, and diagnostics:

sciveo read --proto modbus --transport tcp --host 192.168.0.10 --port 502 --id 1 --address 30001 --kind input --type RAW --count 2
sciveo write --proto mqtt --host broker.local --topic plant/cmd --payload '{"limit":80}' --qos 1 --retain
sciveo emulate --server http --host 0.0.0.0 --port 8080 --data-json '{"status":{"ok":true}}'

Installation

Base install:

pip install sciveo

Useful extras:

pip install "sciveo[mon]"          # host monitoring helpers
pip install "sciveo[net]"          # network, Modbus, SNMP, MQTT helpers
pip install "sciveo[agent]"        # hosted AI agent providers
pip install "sciveo[agent-local]"  # local HF/GGUF runtime support
pip install "sciveo[media]"        # media capture/processing
pip install "sciveo[media-ml]"     # ML model/runtime dependencies
pip install "sciveo[server]"       # API/server helpers
pip install "sciveo[web]"          # Django/web helpers
pip install "sciveo[all]"          # core operations extras

media-ml intentionally does not install Ultralytics. For image/video ML workflows, install both media extras so OpenCV and model runtimes are present:

pip install "sciveo[media,media-ml]"

Sciveo SCIVEYOLO runtime loads .sciveyolo artifacts with PyTorch or ONNX Runtime depending on the artifact engine.

CLI Overview

Show CLI help and version:

sciveo --help
sciveo --version
sciveo help --json
sciveo help monitor
sciveo help monitor --json

Current top-level CLI commands:

init
monitor
watchdog
scan
ssh
read
write
emulate
admin
doctor
fleet
extensions
nvr
rtsp
capture
media-server
media-run
agent
chat
storage
predictors-server

The sciveo help --json manifest is the machine-readable source for command summaries, usage forms, options, notes, and examples.

Configuration

Initialize local configuration:

sciveo init

The default local configuration lives under ~/.sciveo/. API credentials can also be supplied through environment variables where supported, for example:

export SCIVEO_SECRET_ACCESS_KEY="..."

Monitoring

Start host monitoring:

sciveo monitor --period 60

Install monitoring as a service:

sudo sciveo monitor --install --period 60

Write samples to a local path:

sciveo monitor --period 120 --output-path ./monitor.json

Start non-blocking monitoring from Python:

import sciveo

sciveo.monitor(period=120, block=False)

Plant/industrial monitoring uses the plant source:

sciveo monitor --src plant --host 192.168.1.50 --port 502 --period 60 --serial plant-1

Watchdogs

Watchdogs run local checks and execute a command when a condition remains unhealthy.

sciveo watchdog --src memory --threshold 90 --period 10 --execute "systemctl restart app"
sciveo watchdog --src disk --input-path /data --threshold 80 --period 600 --execute "find /data/tmp -type f -mtime +1 -delete"
sciveo watchdog --src network --targets '["1.1.1.1:443","8.8.8.8:53"]' --threshold 3 --period 30 --execute "echo network outage"

For network watchdogs, --threshold means consecutive failed checks before the action runs.

Diagnostics and Fleet

Local diagnostic report:

sciveo doctor
sciveo doctor --render json
sciveo doctor --logs --output-path /tmp/sciveo-doctor.json

Fleet inventory over SSH:

sciveo fleet --host [e-mail] -i ~/.ssh/id_ed25519
sciveo fleet --net 192.168.10.0/24 --users operator,admin -i ~/.ssh/id_ed25519 --render json

Network and Industrial IO

Network scans:

sciveo scan
sciveo scan --net 192.168.0.0/24 --port 22 --timeout 0.5
sciveo scan --health
sciveo scan --health --l2
sciveo scan --host 192.168.0.10 --health --ports '[22,80,443,502,554,161]'

SSH scan and command execution:

sciveo ssh --net 192.168.0.0/24 --users operator,admin -i ~/.ssh/id_ed25519 --list-shell '["hostname","uptime"]'

Modbus reads and writes:

sciveo read --proto modbus --transport tcp --host 192.168.0.10 --port 502 --id 1 --address 30001 --kind input --type RAW --count 2
sciveo write --proto modbus --transport tcp --host 192.168.0.10 --id 1 --reg '[40010,"U16",1,1]' --value 123
sciveo read --proto modbus --action scan --net 192.168.0.0/24 --render text

Serial Modbus:

sciveo read --proto modbus --transport serial --serial-port /dev/ttyUSB0 --baudrate 9600 --bytesize 8 --parity N --stopbits 1 --id 1 --reg '[5039,"U16",0.1,1]'

SNMP, MQTT, and HTTP helpers:

sciveo read --proto snmp --host 192.168.0.1 --oid 1.3.6.1.2.1.1.1.0
sciveo read --proto snmp --host 192.168.0.1 --action walk --oid 1.3.6.1.2.1.1
sciveo write --proto mqtt --host broker.local --topic plant/cmd --payload '{"limit":80}' --qos 1 --retain
sciveo read --proto http --url http://192.168.0.10/status
sciveo write --proto http --url http://192.168.0.10/api/control --value '{"enabled":true}'

Protocol emulators:

sciveo emulate --server modbus --profile custom --host 0.0.0.0 --port 1502 --data-json '{"device_id":7,"holding":{"40010":123}}'
sciveo emulate --server snmp --host 0.0.0.0 --port 1161 --data-json '{"oids":{"1.3.6.1.2.1.1.1.0":"lab-agent"}}'
sciveo emulate --server mqtt --host 0.0.0.0 --port 1883 --data-json '{"retained":{"plant/power":1234}}'
sciveo emulate --server http --host 0.0.0.0 --port 8080 --data-json '{"status":{"ok":true}}'

Admin UI

The admin command is for first-boot and field administration of an edge machine:

sciveo admin
sciveo admin --web --wifi-ap --net 10.137.19.0/24 --ap-ssid sciveo-setup --ap-password CHANGE_ME --admin-auth none
sudo sciveo admin --install --web --wifi-ap --net 10.137.19.0/24 --ap-ssid sciveo-setup --ap-password CHANGE_ME --admin-auth none

The admin UI covers dashboard diagnostics, Ethernet and Wi-Fi setup, service state, pending configuration, and installed service management. Pending configuration is stored under ~/.sciveo/admin/.

VS Code Extension

The Python package can install the bundled VS Code extension asset:

sciveo extensions --install --vscode
sciveo extensions --reinstall --vscode
sciveo extensions --uninstall --vscode

If the editor CLI is not on PATH, set:

export SCIVEO_VSCODE_CLI="/path/to/code"

Extension config is stored under ~/.sciveo/extensions/vscode/.

Encrypted Chat Rooms

Start a room:

sciveo chat --serve ops-room --host 0.0.0.0 --port 8090 --max-clients 5

Join from another terminal:

sciveo chat --client 'sciveo-chat-v1....' --url ws://HOST:8090/ws/chat --name operator-a

Messages use encrypted AES-GCM envelopes, while connection setup uses a shared-token HMAC proof. Display names are decorative; anyone with the shared token is trusted as a room participant.

Persist and reload encrypted room history:

sciveo chat --serve ops-room --output-path ./chat-history.jsonl
sciveo chat --serve ops-room --input-path ./chat-history.jsonl --output-path ./chat-history.jsonl

Suppress decrypted message bodies in server logs:

sciveo chat --serve ops-room --silent

TLS:

sciveo chat --serve ops-room --tls-cert ./chat.crt --tls-key ./chat.key
sciveo chat --client 'sciveo-chat-v1....' --url wss://HOST:8090/ws/chat --name operator-a --tls-no-verify

Agent Console

Interactive agent console:

sciveo agent --provider auto
sciveo agent --profile coder --provider auto

One-shot prompt:

sciveo agent --provider auto --prompt "List the repo root and summarize the important files"

Profiles can be loaded with --profile NAME or --config PATH. Predefined profiles include coding, review, testing, research, and operations-oriented specializations.

Local runtime examples:

sciveo agent --action pull --model org/model-name --alias local-agent-model
sciveo agent --action run --model local-agent-model --host 127.0.0.1 --port 8910 --device mps --context 8192
sciveo agent --provider hf --prompt "Say hello in one sentence"

Agent orchestration uses the chat transport:

sciveo agent --action orchestrate --serve design-room --prompt "Review this module" --agents researcher,coder,reviewer,tester
sciveo agent --action orchestrate --serve design-room --prompt "Plan the next pass" --agent-write-policy discussion-only

Media Capture and Processing

Capture and stream helpers:

sciveo nvr --input-path cams.json
sciveo rtsp --url rtsp://camera/stream --output-path ./clip.mp4
sciveo capture --output-path ./screen.mp4 --fps 10

Run the queue/API-backed media worker:

sciveo media-server
sciveo media-run --mode worker

Run local/offline media processing:

sciveo media-run --input-path ./media --output-path ./media-out --render text
sciveo media-run --processor image-resize --input-path ./input.jpg --output-path ./image-out
sciveo media-run --config pipeline.json --input-path ./input.mp4 --output-path ./video-out

Run local ML media processing:

sciveo media-run --mode ml --processor image-to-text --input-path ./input.jpg --output-path ./ml-out

Local mode does not require API, queue, S3, or cloud credentials. Worker mode is for API/queue/storage-backed jobs.

SCIVEYOLO Object Detection

Sciveo provides a SCIVEYOLO inference runtime in sciveo.ml.images.sciveyolo.

Goals:

• load .sciveyolo artifacts without Ultralytics installed;
• use a Sciveo-owned PyTorch SCIVEYOLO graph for engine="pt";
• preserve a familiar SCIVEYOLO(...).predict(...) style API;
• support SCIVEYOLO model sizes n, s, m, l, and x through one generic scale-parameterized network;
• keep build-time conversion separate from production runtime.

Basic use:

from sciveo.ml.images.sciveyolo import SCIVEYOLO

model = SCIVEYOLO("model.sciveyolo")
results = model.predict("image.jpg", conf=0.25, iou=0.7)

Build a Sciveo artifact from a PyTorch checkpoint:

from sciveo.ml.images.sciveyolo import SCIVEYOLO

SCIVEYOLO.build("detector.pt", "detector.sciveyolo")

The default build engine is pt, which stores a state dict and metadata inside the .sciveyolo file. The artifact metadata includes engine, runtime, architecture, scale, model_size, variant, class names, image size, and source hash.

Auto-build sidecar behavior:

model = SCIVEYOLO("detector.pt")

When given a .pt path, Sciveo first looks for a same-name .sciveyolo sidecar next to it. If present, that artifact is loaded. If absent, Sciveo attempts to build it with engine="pt" and then loads the generated artifact.

Build an ONNX artifact only when explicitly wanted:

SCIVEYOLO.build("detector.pt", "detector-onnx.sciveyolo", engine="onnx")

Build-time conversion may use a separate environment with export tooling. The production runtime only needs the dependencies required by the artifact engine, for example PyTorch for engine="pt" or ONNX Runtime for engine="onnx".

Runtime options:

model = SCIVEYOLO("model.sciveyolo", device="cpu", nms_method="numpy")
model = SCIVEYOLO("model.sciveyolo", fuse=True)
model = SCIVEYOLO("model.sciveyolo", channels_last=True)

For CPU deployment, ONNX Runtime can be faster than the PyTorch engine on some machines. For GPU deployment, engine="pt" is the most portable path, while ONNX/TensorRT performance depends on the installed runtime and GPU generation.

Predictors API Server

Start the predictors API service:

sciveo predictors-server --port 8080

This command starts the configured Sciveo API predictor server and keeps it running as a long-lived process.

Local S3-Compatible Storage

Start a local S3-compatible service:

sciveo storage --s3 --paths '["/mnt/d1","/mnt/d2"]' --port 9000 --parallel 32 --health-check-interval 10800

A JSON config can also be supplied:

{
  "paths": ["/mnt/d1", "/mnt/d2"],
  "access_key": "sciveo",
  "secret_key": "CHANGE_ME",
  "region": "us-east-1",
  "storage_name": "storage",
  "db_backend": "sqlite",
  "db_path": "~/.sciveo/storage/storage-s3.sqlite3",
  "path_health_check_interval": 10800
}

sciveo storage --s3 --config ./storage.json

--paths are mounted directories, not raw block devices. Object metadata is stored in ~/.sciveo/storage/<storage-name>-s3.sqlite3 by default with the SQLite backend, or in the configured SQL metadata DB when db_path/--db-path is supplied. Use storage_name/--storage-name to keep multiple storage processes separate.

For heavier production metadata concurrency, use PostgreSQL:

{
  "s3": {
    "paths": ["/mnt/d1", "/mnt/d2", "/mnt/d3"],
    "access_key": "sciveo",
    "secret_key": "CHANGE_ME",
    "storage_name": "video-cache",
    "db": {
      "backend": "postgres",
      "url": "postgresql://sciveo:CHANGE_ME@127.0.0.1:5432/sciveo_storage"
    }
  }
}

The same settings can also be supplied as flat keys (db_backend, db_url) or CLI options (--db-backend postgres --db-url ...). Install the DB extra or psycopg2 before selecting PostgreSQL.

On startup, the service runs a metadata sync pass over healthy storage paths: files that exist on disk but are missing from the SQL metadata DB are added, metadata rows for files missing from currently healthy paths are removed, and metadata rows whose root path is unhealthy are pruned by root index. Run the same reconciliation without starting the server with:

sciveo storage --s3 --sync --config ./storage.json
sciveo storage --s3 --sync --dry-run --config ./storage.json
sciveo storage --s3 --sync --since 10m --config ./storage.json

--since accepts a Unix timestamp, an ISO timestamp, or a relative duration such as 10m, 2h, or 1d. It is intended for fast catch-up after a full index build, for example when preparing a PostgreSQL metadata DB while the SQLite-backed service is still live. Incremental sync only reconciles files with filesystem mtimes newer than the timestamp and only prunes recently updated metadata rows; run a full --sync when you need a complete consistency audit.

If a configured path becomes unavailable or unwritable, the running process marks that path unhealthy and excludes it from new object placement. Object metadata for that root is removed with an indexed path-level delete, so S3 listings omit those keys and GET/HEAD behave like cache misses. Failed paths are probed periodically and automatically return to the write pool when the health check succeeds; a later full --sync can rebuild metadata for files still present on the recovered path. Configure the probe interval with --health-check-interval, path_health_check_interval, or SCIVEO_STORAGE_PATH_HEALTH_CHECK_INTERVAL.

Object listing uses the bucket/key index with a prefix key range rather than a table scan. Empty bucket deletion removes the whole bucket tree below each healthy storage path in one filesystem operation; dead paths are skipped because their object metadata has already been pruned as cache-missing data.

Python client example:

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="http://127.0.0.1:9000",
    aws_access_key_id="sciveo",
    aws_secret_access_key="CHANGE_ME",
    region_name="us-east-1",
)

s3.upload_file("clip.mp4", "media", "clips/clip.mp4")
s3.download_file("media", "clips/clip.mp4", "clip-copy.mp4")

Local workers running on the same storage machine can resolve an object to its committed file path without downloading it through S3:

from sciveo.storage.local import StorageLocalClient

storage = StorageLocalClient.from_config("/etc/sciveo/storage-s3.json")
storage.create_bucket("media")
path = storage.path("media", "clips/clip.mp4")

# Use path directly with local video/image processing code.
storage.copy("media", "clips/clip.mp4", dst_key="processed/clip.mp4")
storage.move("media", "tmp/clip.mp4", dst_key="queue/0/clip.mp4")
storage.delete_objects("media", ["processed/clip.mp4", "queue/0/clip.mp4"])
storage.delete_bucket("media")

StorageLocalClient reads the same storage config and SQL metadata DB as the server. It only returns paths for committed objects whose files still exist, rejects metadata paths outside the configured storage roots, and updates both object files and metadata for local bucket, copy, move, and delete operations. move() defaults to no_copy=True: the file is renamed on its current storage path and only the bucket/key metadata changes, so changing a key does not trigger an inter-disk copy when the destination key hashes to another path. Use move(..., no_copy=False) only when the old copy/delete behavior is desired.

Experiments Client

The experiment helpers expose project runs, parameter sampling, datasets, scoring, plots, metadata, local execution, and optional remote synchronization. They are useful for ML, AI, research, and engineering scripts where each run should have a known configuration and a recorded result.

Minimal pattern:

import sciveo

def run_once():
    with sciveo.open() as experiment:
        experiment.log({"message": "hello experiment"})
        experiment.score(0.0)

sciveo.start(
    project="example-project",
    function=run_once,
    configuration={},
    remote=False,
    count=1,
)

Run a project:

import sciveo

def evaluate_model():
    with sciveo.open() as experiment:
        learning_rate = experiment.config.learning_rate
        experiment.log("learning_rate", learning_rate)
        experiment.score(0.94)

sciveo.start(
    project="example-project",
    function=evaluate_model,
    configuration={"learning_rate": {"values": [0.001, 0.01]}},
    remote=False,
    count=2,
)

Remote synchronization requires a configured Sciveo API account.

Experiment Concepts

• Project: a named ML, research, or engineering workspace containing related runs.
• Experiment: one run with a sampled configuration, measurements, outputs, and score.
• Configuration: parameter values used by the run.
• Dataset records: structured references to input data, split definitions, or generated data artifacts.
• Score: numeric or structured result used for comparison and optimization.
• Local mode: runs experiments on the current machine without API synchronization.
• Remote mode: synchronizes project and experiment data through the Sciveo API when configured.

Example with dataset and score metadata:

import sciveo

def evaluate_dataset():
    with sciveo.open() as experiment:
        experiment.dataset({
            "name": "sensor-window-001.csv",
            "split": {"train": 0.8, "test": 0.2},
        })
        experiment.eval("rmse", 0.034)
        experiment.eval("mae", 0.021)
        experiment.score(0.93)

sciveo.start(
    project="sensor-eval",
    function=evaluate_dataset,
    configuration={},
    remote=False,
    count=1,
)

Example local parameter sweep:

import sciveo

def calibrate():
    with sciveo.open() as experiment:
        window = experiment.config.window
        threshold = experiment.config.threshold
        experiment.log({"window": window, "threshold": threshold})
        experiment.score(0.8)

sciveo.start(
    project="lab-calibration",
    function=calibrate,
    configuration={
        "window": {"values": [32, 64, 128]},
        "threshold": {"values": [0.1, 0.2, 0.3]},
    },
    remote=False,
    sampler="grid",
)

Sciveo does not force a specific analysis or ML stack. Experiments can call NumPy, SciPy, scikit-learn, PyTorch, TensorFlow, OpenCV, custom sensor clients, or any other Python code that fits the workflow.

Python Module Map

Common package areas:

• sciveo.monitoring: metrics, watchdogs, monitoring CLI.
• sciveo.network: scan, SSH, Modbus, SNMP, MQTT, HTTP, emulators.
• sciveo.admin: edge admin web UI and service helpers.
• sciveo.ops: doctor and fleet diagnostics.
• sciveo.agents: agent console, providers, local runtimes.
• sciveo.chat: encrypted chat server/client transport.
• sciveo.media: capture, media CLI, pipeline workers.
• sciveo.ml.images: image ML helpers, SCIVEYOLO inference, embeddings, descriptions, image transforms.
• sciveo.storage: local S3-compatible object store.
• sciveo.api: API clients and predictor server.
• sciveo.db, sciveo.web, sciveo.content, sciveo.tools: shared support modules.

Development Checks

Useful local checks:

python -m py_compile sciveo/cli.py sciveo/ml/images/sciveyolo.py sciveo/ml/images/sciveyolo_torch.py
python -m unittest discover -s test -p "test_*.py" -v

For SCIVEYOLO runtime validation, use a UT-capable build environment to create .sciveyolo artifacts, then test production loading in an environment that has PyTorch/OpenCV/NumPy but no Ultralytics installed.

Contact

Pavlin Georgiev
[e-mail]