Metadata-Version: 2.1
Name: sciveo
Version: 0.2.51
Description-Content-Type: text/markdown
Provides-Extra: mon
Provides-Extra: agent
Provides-Extra: agent-local
Provides-Extra: net
Provides-Extra: server
Provides-Extra: chat
Provides-Extra: media
Provides-Extra: media-ml
Provides-Extra: sciveyolo
Provides-Extra: sciveyolo-gpu
Provides-Extra: sciveyolo-trt
Provides-Extra: web
Provides-Extra: db
Provides-Extra: power
Provides-Extra: energy
Provides-Extra: all
Provides-Extra: ml

# 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:

```python
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:

```shell
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:

```shell
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
```

```python
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:

```shell
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:

```shell
pip install sciveo
```

Useful extras:

```shell
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:

```shell
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:

```shell
sciveo --help
sciveo --version
sciveo help --json
sciveo help monitor
sciveo help monitor --json
```

Current top-level CLI commands:

```text
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:

```shell
sciveo init
```

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

```shell
export SCIVEO_SECRET_ACCESS_KEY="..."
```

## Monitoring

Start host monitoring:

```shell
sciveo monitor --period 60
```

Install monitoring as a service:

```shell
sudo sciveo monitor --install --period 60
```

Write samples to a local path:

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

Start non-blocking monitoring from Python:

```python
import sciveo

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

Plant/industrial monitoring uses the `plant` source:

```shell
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.

```shell
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:

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

Fleet inventory over SSH:

```shell
sciveo fleet --host operator@edge.local -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:

```shell
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:

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

Modbus reads and writes:

```shell
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:

```shell
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:

```shell
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:

```shell
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:

```shell
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:

```shell
sciveo extensions --install --vscode
sciveo extensions --reinstall --vscode
sciveo extensions --uninstall --vscode
```

If the editor CLI is not on `PATH`, set:

```shell
export SCIVEO_VSCODE_CLI="/path/to/code"
```

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

## Encrypted Chat Rooms

Start a room:

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

Join from another terminal:

```shell
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:

```shell
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:

```shell
sciveo chat --serve ops-room --silent
```

TLS:

```shell
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:

```shell
sciveo agent --provider auto
sciveo agent --profile coder --provider auto
```

One-shot prompt:

```shell
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:

```shell
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:

```shell
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:

```shell
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:

```shell
sciveo media-server
sciveo media-run --mode worker
```

Run local/offline media processing:

```shell
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:

```shell
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:

```python
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:

```python
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:

```python
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:

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

Build a TensorRT-backed artifact when running on NVIDIA CUDA hosts:

```python
SCIVEYOLO.build("detector.pt", "detector-trt.sciveyolo", engine="trt")
```

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"`, ONNX Runtime for `engine="onnx"`, or
ONNX Runtime GPU plus TensorRT for `engine="trt"`.

Install the runtime extra that matches the deployment target:

```shell
pip install "sciveo[sciveyolo]"
pip install "sciveo[sciveyolo-gpu]"
pip install "sciveo[sciveyolo-trt]"
```

Use a fresh pyenv for the GPU/TRT extras when possible, because
`onnxruntime` and `onnxruntime-gpu` provide the same `onnxruntime` Python
module. The TRT extra is intended for CUDA/NVIDIA machines with compatible
drivers and TensorRT libraries.

Runtime options:

```python
model = SCIVEYOLO("model.sciveyolo", device="cpu", nms_method="numpy")
model = SCIVEYOLO("model.sciveyolo", fuse=True)
model = SCIVEYOLO("model.sciveyolo", channels_last=True)
model = SCIVEYOLO("model.sciveyolo", device="cuda:0", engine="auto", auto_engine_source="sample-video.mp4")
```

Native fine-tuning uses UT-style object-detection dataset YAML files:

```python
model = SCIVEYOLO("coco-detector.sciveyolo")
result = model.train(
    data="/datasets/coco128/data.yaml",
    project="/models/object-detection",
    name="coco128-sciveyolo-m",
    epochs=8,
    batch=24,
    augment=False,
    optimizer="SGD",
    lr0=0.005,
    lrf=0.1,
    amp=False,
)
```

The trainer writes `weights/last.pt`, `weights/best.pt`,
`weights/last.sciveyolo`, `weights/best.sciveyolo`, `args.yaml`, and
`results.csv` under `project/name`.

Evaluate an artifact on a dataset split:

```python
model = SCIVEYOLO("coco-detector.sciveyolo")
val_metrics = model.evaluate(data="/datasets/coco128/data.yaml", split="val")
test_metrics = model.test(data="/datasets/coco128/data.yaml")
```

`evaluate()` reports both native validation loss for PyTorch artifacts and
Sciveo object-detection AP/FP metrics. `test()` is the same evaluator with
`split="test"` by default.

`engine="auto"` looks for compatible `.sciveyolo` artifacts near the requested
model, checks what the selected device/runtime can actually load, runs a small
probe when multiple candidates are available, and then sets `model.engine` to
the selected engine.

Pass `auto_engine_source` as an image, video, frame array, or list of sources to
make the probe representative of the deployment workload. Without a source,
Sciveo logs that it is falling back to a synthetic frame.

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:

```shell
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:

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

A JSON config can also be supplied:

```json
{
  "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
}
```

```shell
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:

```json
{
  "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:

```shell
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:

```python
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")
```

Sciveo also provides a boto3-like remote client that keeps the normal S3
methods and adds Sciveo-native metadata search endpoints:

```python
import sciveo.storage.s3

s3 = sciveo.storage.s3.client(
    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")
objects = s3.search_objects(Bucket="media", Prefix="clips/", Period=7200)
stats = s3.search_stats(Bucket="media", Prefix="clips/")
```

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

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```shell
python -m py_compile sciveo/cli.py sciveo/ml/images/sciveyolo/model.py sciveo/ml/images/sciveyolo/torch_net.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  
pavlin@softel.bg
