qapu-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{qapu_cli-0.3.0 → qapu_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qapu-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: CLI client for the Qapu API - built for the Hermes agent, but usable by anyone talking to api.ovoo.com.tr from outside the Swarm.
 Author: OVOO Technology
 Classifier: Programming Language :: Python :: 3
@@ -49,6 +49,7 @@ Either way installs a `qapu` command (see `pyproject.toml`'s `[project.scripts]`
 ## Commands
 
 ```bash
+qapu --version                       # print the installed qapu-cli version and exit
 qapu health                          # GET /health - no auth, quick connectivity check
 qapu device list                     # GET /hermes/devices - every device, bulk, as a table
 qapu device list --json              # same data, raw JSON
@@ -76,6 +77,18 @@ qapu data <device_id> --search vrms  # substring match on variable ID, e.g. VRMS
 
 `qapu data`'s family filters (`--energy`/`--gsm`/`--voltage`/`--current`/`--battery`) are a union - passing more than one shows variables matching any of them. `--search` narrows whatever they leave (or the full list, if none were given) further, by a case-insensitive substring match on the variable ID - the way to pin down an exact family like `VRMS_R`/`VRMS_S`/`VRMS_T`. Values come from the measurement cache's rolling buffer (the same source `/measurement/{device_id}/last/{variable_id}` reads from), not a fresh device poll - "latest" means the most recent packet already ingested, not real-time.
 
+```bash
+qapu trend <device_id> <variable_id>            # GET /hermes/trend/{device_id}/{variable_id} - last 20 raw readings + trend
+qapu trend <device_id> <variable_id> --last 50  # last N raw readings instead of the default 20
+qapu trend <device_id> <variable_id> --days 2   # daily min/avg/max over the last 2 days, instead of raw readings
+qapu trend <device_id> <variable_id> --days 30  # ...or the last month
+qapu trend <device_id> <variable_id> --json
+```
+
+`qapu trend` shows a per-variable history plus a simple linear-regression trend line (slope + direction). Two modes, picked by which option you pass:
+- **Raw readings** (`--last N`, default `N=20`): the measurement cache's rolling buffer - bounded to its own depth (~50 most recent packets), *not* a time window. Good for "what's it doing right now."
+- **Daily aggregates** (`--days N`): one row per calendar day (min/avg/max/count), from the same cache the `/measurement/{device_id}/history` endpoint reads - this is what actually covers multi-day/month windows, since the raw buffer doesn't go back that far. `--days` wins if both are given.
+
 Filtering (`--status`/`--model`/`--limit`) happens client-side in the CLI, not on the server - fine at the current fleet size, worth moving server-side (`GET /hermes/devices?status=...`) if it ever grows large enough to matter.
 
 ## Auth (current placeholder - read this before pointing at production)

{qapu_cli-0.3.0 → qapu_cli-0.4.0}/README.md

@@ -37,6 +37,7 @@ Either way installs a `qapu` command (see `pyproject.toml`'s `[project.scripts]`
 ## Commands
 
 ```bash
+qapu --version                       # print the installed qapu-cli version and exit
 qapu health                          # GET /health - no auth, quick connectivity check
 qapu device list                     # GET /hermes/devices - every device, bulk, as a table
 qapu device list --json              # same data, raw JSON
@@ -64,6 +65,18 @@ qapu data <device_id> --search vrms  # substring match on variable ID, e.g. VRMS
 
 `qapu data`'s family filters (`--energy`/`--gsm`/`--voltage`/`--current`/`--battery`) are a union - passing more than one shows variables matching any of them. `--search` narrows whatever they leave (or the full list, if none were given) further, by a case-insensitive substring match on the variable ID - the way to pin down an exact family like `VRMS_R`/`VRMS_S`/`VRMS_T`. Values come from the measurement cache's rolling buffer (the same source `/measurement/{device_id}/last/{variable_id}` reads from), not a fresh device poll - "latest" means the most recent packet already ingested, not real-time.
 
+```bash
+qapu trend <device_id> <variable_id>            # GET /hermes/trend/{device_id}/{variable_id} - last 20 raw readings + trend
+qapu trend <device_id> <variable_id> --last 50  # last N raw readings instead of the default 20
+qapu trend <device_id> <variable_id> --days 2   # daily min/avg/max over the last 2 days, instead of raw readings
+qapu trend <device_id> <variable_id> --days 30  # ...or the last month
+qapu trend <device_id> <variable_id> --json
+```
+
+`qapu trend` shows a per-variable history plus a simple linear-regression trend line (slope + direction). Two modes, picked by which option you pass:
+- **Raw readings** (`--last N`, default `N=20`): the measurement cache's rolling buffer - bounded to its own depth (~50 most recent packets), *not* a time window. Good for "what's it doing right now."
+- **Daily aggregates** (`--days N`): one row per calendar day (min/avg/max/count), from the same cache the `/measurement/{device_id}/history` endpoint reads - this is what actually covers multi-day/month windows, since the raw buffer doesn't go back that far. `--days` wins if both are given.
+
 Filtering (`--status`/`--model`/`--limit`) happens client-side in the CLI, not on the server - fine at the current fleet size, worth moving server-side (`GET /hermes/devices?status=...`) if it ever grows large enough to matter.
 
 ## Auth (current placeholder - read this before pointing at production)

{qapu_cli-0.3.0 → qapu_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qapu-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "CLI client for the Qapu API - built for the Hermes agent, but usable by anyone talking to api.ovoo.com.tr from outside the Swarm."
 readme = "README.md"
 requires-python = ">=3.10"

{qapu_cli-0.3.0 → qapu_cli-0.4.0}/qapu_cli/main.py

@@ -5,6 +5,7 @@
 
 import json
 from datetime import datetime, timezone
+from importlib.metadata import PackageNotFoundError, version as _package_version
 from typing import Any, Optional
 
 import httpx
@@ -22,6 +23,33 @@ app.add_typer(variable_app, name="variable")
 
 console = Console()
 
+
+# --version - Reads the Installed Package Metadata Directly, so it's
+# Always in Sync with pyproject.toml's version - Nothing to Hand-Bump Here.
+def _version_callback(show_version: bool) -> None:
+
+	# Only Act if --version was Actually Passed
+	if not show_version:
+		return
+
+	# Try to Resolve the Installed Version
+	try:
+		typer.echo(_package_version("qapu-cli"))
+
+	# Not Installed as a Package (e.g. Running Straight from Source)
+	except PackageNotFoundError:
+		typer.echo("unknown (not installed as a package)")
+
+	# Exit Before Typer Falls Through to "No Command Given" Help Text
+	raise typer.Exit()
+
+
+@app.callback()
+def _root(
+	version: Optional[bool] = typer.Option(None, "--version", callback=_version_callback, is_eager=True, help="Show the installed qapu-cli version and exit."),
+) -> None:
+	"""Qapu API client CLI."""
+
 # Segment Name -> ID, Matching Constants.Variable_Segment (common/qapu_common/constants.py)
 SEGMENTS = {
 	"unknown": 0,
@@ -544,6 +572,173 @@ def device_data(
 	console.print(_build_data_table(sorted(readings, key=lambda r: r.get("Variable_ID") or "")))
 
 
+# Simple Least-Squares Slope - No Extra Dependency for This, and n < 2
+# (Or a Vertical/Degenerate x Range) Just Means "Not Enough Points Yet"
+def _linear_slope(xs: list[float], ys: list[float]) -> Optional[float]:
+
+	# Not Enough Points to Fit a Line
+	n = len(xs)
+	if n < 2:
+		return None
+
+	# Compute Means
+	mean_x = sum(xs) / n
+	mean_y = sum(ys) / n
+
+	# Compute Slope via Covariance / Variance
+	numerator = sum((x - mean_x) * (y - mean_y) for x, y in zip(xs, ys))
+	denominator = sum((x - mean_x) ** 2 for x in xs)
+
+	# Degenerate x Range (All Same Timestamp/Day) - No Meaningful Slope
+	if denominator == 0:
+		return None
+
+	# Return the Slope
+	return numerator / denominator
+
+
+# Describe a Slope's Direction in Turkish, for the Trend Summary Line
+def _slope_direction(slope: float) -> str:
+
+	# Resolve Direction Label
+	if slope > 0:
+		return "artıyor"
+	if slope < 0:
+		return "azalıyor"
+	return "sabit"
+
+
+# Get One Variable's Trend on One Device - Either the Last N Raw Buffered
+# Readings, or Daily Min/Avg/Max Over the Last N Days (Mutually Exclusive -
+# --days Wins if Both are Given)
+@app.command("trend")
+def device_trend(
+	device_id: str = typer.Argument(..., help="Device ID."),
+	variable_id: str = typer.Argument(..., help="Variable ID (e.g. VRMS_R)."),
+	last: int = typer.Option(20, "--last", help="Show the last N raw buffered readings. Bounded by the buffer's own depth (~50 most recent packets) - not a time window."),
+	days: Optional[int] = typer.Option(None, "--days", help="Show daily min/avg/max over the last N days instead of raw readings (e.g. --days 2, --days 30 for a month). Takes priority over --last if both are given."),
+	as_json: bool = typer.Option(False, "--json", help="Print raw JSON instead of a table."),
+):
+	"""Trend for one variable on one device: recent readings or daily min/avg/max (GET /hermes/trend/{device_id}/{variable_id})."""
+
+	# Fetch the Trend - Raw Series + Full Daily History, Already Enriched
+	t: dict[str, Any] = client.get(f"/hermes/trend/{device_id}/{variable_id}")
+
+	# JSON Output - Everything at Once, no Slicing/Stats Applied
+	if as_json:
+
+		# Print Raw JSON
+		typer.echo(json.dumps(t, indent=2))
+		return
+
+	# Header Line - What Variable, on What Device
+	description = t.get("Description") or "-"
+	unit = t.get("Unit") or "-"
+	segment_name = t.get("Segment") or "-"
+	console.print(f"[bold]{t.get('Variable_ID') or variable_id}[/bold] - {description} ({unit}) - {segment_name}")
+
+	# --- Daily Mode (--days) ---
+	if days is not None:
+
+		# Resolve the Last N Days, Sorted Chronologically
+		daily: dict[str, Any] = t.get("Daily") or {}
+		sorted_days = sorted(daily.keys())[-days:]
+
+		# Nothing to Show
+		if not sorted_days:
+			typer.echo("Bu değişken için günlük veri yok.")
+			return
+
+		# Build the Daily Table
+		table = Table(show_header=True, header_style="bold")
+		table.add_column("DATE")
+		table.add_column("MIN", justify="right")
+		table.add_column("AVG", justify="right")
+		table.add_column("MAX", justify="right")
+		table.add_column("COUNT", justify="right")
+
+		# Populate Rows, Collecting (Day Index, Avg) Pairs for the Slope
+		xs: list[float] = []
+		ys: list[float] = []
+		for i, day in enumerate(sorted_days):
+
+			# Resolve the Day's Node
+			node = daily.get(day) or {}
+			avg = node.get("Avg")
+
+			# Add the Row
+			table.add_row(
+				day,
+				f"{node.get('Min'):g}" if isinstance(node.get("Min"), (int, float)) else "-",
+				f"{avg:g}" if isinstance(avg, (int, float)) else "-",
+				f"{node.get('Max'):g}" if isinstance(node.get("Max"), (int, float)) else "-",
+				str(node.get("Count", "-")),
+			)
+
+			# Track for the Slope (Trend Over the Daily Averages)
+			if isinstance(avg, (int, float)):
+				xs.append(float(i))
+				ys.append(float(avg))
+
+		# Print the Table
+		console.print(table)
+
+		# Print the Trend Summary, if There Were Enough Points
+		slope = _linear_slope(xs, ys)
+		if slope is not None:
+			typer.echo(f"Trend: {slope:+.4f} {unit}/gün ({_slope_direction(slope)})")
+
+		return
+
+	# --- Raw Readings Mode (Default, --last) ---
+	series: list = t.get("Series") or []
+	series = series[-last:] if last > 0 else series
+
+	# Nothing Buffered Yet
+	if not series:
+		typer.echo("Bu değişken için henüz buffer verisi yok.")
+		return
+
+	# Build the Readings Table, Chronological (Oldest First)
+	table = Table(show_header=True, header_style="bold")
+	table.add_column("TIME")
+	table.add_column("VALUE", justify="right")
+
+	# Populate Rows, Collecting (Elapsed Hours, Value) Pairs for the Slope
+	xs = []
+	ys = []
+	first_time: Optional[datetime] = None
+	for entry in series:
+
+		# Skip Malformed Entries Defensively
+		if not isinstance(entry, list) or len(entry) != 2:
+			continue
+
+		# Unpack the Entry
+		raw_time, value = entry
+		table.add_row(_relative_time(raw_time), f"{value:g}" if isinstance(value, (int, float)) else "-")
+
+		# Track for the Slope (Trend Over Elapsed Hours Since the First Point)
+		try:
+			parsed_time = datetime.fromisoformat(raw_time)
+			if first_time is None:
+				first_time = parsed_time
+			xs.append((parsed_time - first_time).total_seconds() / 3600)
+			ys.append(float(value))
+		except (ValueError, TypeError):
+			continue
+
+	# Print the Table
+	console.print(table)
+
+	# Print Min/Avg/Max and the Trend Summary
+	if ys:
+		typer.echo(f"Min: {min(ys):g}  Avg: {sum(ys) / len(ys):g}  Max: {max(ys):g}")
+	slope = _linear_slope(xs, ys)
+	if slope is not None:
+		typer.echo(f"Trend: {slope:+.4f} {unit}/saat ({_slope_direction(slope)})")
+
+
 if __name__ == "__main__":
 
 	# Run the Typer App

{qapu_cli-0.3.0 → qapu_cli-0.4.0}/qapu_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qapu-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: CLI client for the Qapu API - built for the Hermes agent, but usable by anyone talking to api.ovoo.com.tr from outside the Swarm.
 Author: OVOO Technology
 Classifier: Programming Language :: Python :: 3
@@ -49,6 +49,7 @@ Either way installs a `qapu` command (see `pyproject.toml`'s `[project.scripts]`
 ## Commands
 
 ```bash
+qapu --version                       # print the installed qapu-cli version and exit
 qapu health                          # GET /health - no auth, quick connectivity check
 qapu device list                     # GET /hermes/devices - every device, bulk, as a table
 qapu device list --json              # same data, raw JSON
@@ -76,6 +77,18 @@ qapu data <device_id> --search vrms  # substring match on variable ID, e.g. VRMS
 
 `qapu data`'s family filters (`--energy`/`--gsm`/`--voltage`/`--current`/`--battery`) are a union - passing more than one shows variables matching any of them. `--search` narrows whatever they leave (or the full list, if none were given) further, by a case-insensitive substring match on the variable ID - the way to pin down an exact family like `VRMS_R`/`VRMS_S`/`VRMS_T`. Values come from the measurement cache's rolling buffer (the same source `/measurement/{device_id}/last/{variable_id}` reads from), not a fresh device poll - "latest" means the most recent packet already ingested, not real-time.
 
+```bash
+qapu trend <device_id> <variable_id>            # GET /hermes/trend/{device_id}/{variable_id} - last 20 raw readings + trend
+qapu trend <device_id> <variable_id> --last 50  # last N raw readings instead of the default 20
+qapu trend <device_id> <variable_id> --days 2   # daily min/avg/max over the last 2 days, instead of raw readings
+qapu trend <device_id> <variable_id> --days 30  # ...or the last month
+qapu trend <device_id> <variable_id> --json
+```
+
+`qapu trend` shows a per-variable history plus a simple linear-regression trend line (slope + direction). Two modes, picked by which option you pass:
+- **Raw readings** (`--last N`, default `N=20`): the measurement cache's rolling buffer - bounded to its own depth (~50 most recent packets), *not* a time window. Good for "what's it doing right now."
+- **Daily aggregates** (`--days N`): one row per calendar day (min/avg/max/count), from the same cache the `/measurement/{device_id}/history` endpoint reads - this is what actually covers multi-day/month windows, since the raw buffer doesn't go back that far. `--days` wins if both are given.
+
 Filtering (`--status`/`--model`/`--limit`) happens client-side in the CLI, not on the server - fine at the current fleet size, worth moving server-side (`GET /hermes/devices?status=...`) if it ever grows large enough to matter.
 
 ## Auth (current placeholder - read this before pointing at production)