qapu-cli 0.6.2__tar.gz → 0.6.4__tar.gz

{qapu_cli-0.6.2 → qapu_cli-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qapu-cli
-Version: 0.6.2
+Version: 0.6.4
 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
@@ -182,7 +182,10 @@ qapu stream list <device_id> [--page N] [--size N] [--json]   # GET /hermes/stre
 qapu stream get <stream_id>                                     # GET /hermes/stream/detail/{stream_id}
 
 qapu synthesis list [--device-id] [--variable-id] [--active/--inactive] [--json]   # GET /hermes/synthesis - derived-metric calculation rules
-
+qapu synthesis get <rule_id> [--json]                                             # GET /hermes/synthesis/{rule_id}
+qapu synthesis add <variable_id> --required-variables A,B,C --calculation '{"formula": "A + B"}' [--device-id] [--conditions] [--min-value] [--max-value] [--priority] [--active/--inactive] [--description]  # POST /hermes/synthesis
+qapu synthesis update <rule_id> [--variable-id] [--required-variables] [--calculation] [--device-id] [--conditions] [--min-value] [--max-value] [--priority] [--active/--inactive] [--description]  # PUT /hermes/synthesis/{rule_id}
+qapu synthesis delete <rule_id>                                                    # DELETE /hermes/synthesis/{rule_id}
 qapu user-role list [--json] [--limit N]                # GET /hermes/user_roles - e.g. admin/farmer/technician, NOT the User class itself (PII, deliberately excluded)
 qapu user-role get <role_id> [--json]                    # GET /hermes/user_roles/{id}
 qapu user-role add <id> "Name" [--description]           # POST /hermes/user_roles - ID is REQUIRED, this catalog's ID is NOT auto-increment
@@ -200,6 +203,20 @@ qapu project update <project_id> [--name] [--description] [--active/--inactive]
 qapu project delete <project_id>                               # DELETE /hermes/projects/{project_id}
 ```
 
+**`synthesis` extended to full CRUD (2026-09-03)**, per direct user correction after the read-only version shipped the day before ("qapu synthesis için tam crud yapmamışsın sadece list var"). The 2026-09-02 read-only version was a faithful reflection of the domain class at the time - `Synthesized_Metrics` genuinely had no `add()`/`update()`/`delete()`, only `get_list()`. Added `detail()`/`add()`/`update()`/`delete()` to `common/qapu_common/domain/synthesized_metrics.py` (following the same partial-update/cache-invalidation pattern every other domain class in this session uses), then wired all four into `services/api/src/routers/hermes.py` and the CLI. `--required-variables`/`--conditions` take comma-separated/JSON-string input respectively (`Required_Variables` is a plain list, `Conditions`/`Calculation` are JSON columns) - `--calculation`/`--conditions` are validated as JSON client-side before the request goes out, with a clear error instead of a confusing 400 from the API. New unit tests in `common/tests/test_synthesized_metrics.py` (detail/add/update/delete, 10 new cases) - 502 tests passing.
+
+**Two real production findings surfaced while live-testing this, neither a bug in the new code, both since resolved (see CLAUDE.md's 2026-09-03 entries for the full incident/recovery detail)**:
+1. **`synthesis_variable_rules` turned out to be completely empty in production at the time** - `qapu synthesis list` had been showing 12 rules, but that was a stale Redis cache with nothing backing it in the actual table. Force-refreshing that cache to verify the DB state (`Synthesized_Metrics().get_list(update=True)`) deleted the cache key without anything to refill it from, since the DB read came back empty - and since `synthesize_measurements()` (`common/qapu_common/domain/measurement.py`, called on every real device packet by `services/data`) reads through that same cache, this briefly took real, actively-used synthesis logic out of production, not just cleared a harmless stale copy. **Recovered same day**: the user pulled a dump of the equivalent table from the legacy monolith's own (separate, pre-migration) database via pgAdmin and handed over 9 real rule definitions (weather-related ones deliberately excluded), re-inserted via `Synthesized_Metrics().add()` - formulas/required-variables/conditions/min-max/description preserved verbatim. A real ordering bug surfaced in the restored data itself (not caused by the restore) - `PF_IMB` depends on `PF_AVG` but was ID-ordered before it in the legacy dump, so it was silently skipped every evaluation; fixed by re-inserting `PF_AVG` before `PF_IMB` so ID order matches the dependency. All 9 rules verified correct via a real `calculate_synthesized_metrics()` run.
+2. **A "global" rule (`Device_ID="0"`, applied to every device) could not be added at all** - `synthesis_variable_rules.device_id` is a foreign key into `devices.id`, and there was no `id='0'` placeholder row in `devices` (unlike `projects`/`statuses`, which do have a real `id=0` "Unknown" row). **Fixed same day, per explicit user request**: added `devices.id='0'` ("Unknown Device", `Status_ID`/`Project_ID` both `0`, both already real "Unknown" rows) via `Device().add()`; `Device.list()` (`common/qapu_common/domain/device.py`) updated to exclude `id="0"` (same exclusion `Project.list()` already applies to its own Unknown row) so this placeholder never appears in `qapu device list`/`GET /hermes/devices` as if it were a real device.
+
+Live-tested against real prod data throughout: the original add→get→update→delete→get(404) cycle on a disposable rule (before the empty-table discovery); the 9-rule restore verified both via `synthesis list` and a real `calculate_synthesized_metrics()` computation; `device list` confirmed to still show exactly 11 real devices, `"0"` excluded.
+
+**`--priority` added the same day, per direct user request** ("priority sırasını sen hesaplanacak verilere göre düzenle") - rules are evaluated in `(Priority, ID)` order, and a rule can only see another rule's output if that rule already ran, so relying on insertion (ID) order alone is fragile. `synthesis_variable_rules.priority` turned out to already be a real DB column (`integer NOT NULL DEFAULT 1`) that `common/qapu_common/database/models.py`'s ORM model simply never declared - `get_list()` had been hardcoding `Priority=1` the whole time rather than reading it. Fixed by adding the column to the model; `get_list()`/`add()`/`update()` now read/write it for real. The 9 restored rules were backfilled with real values (independent rules = `1`, one-level-dependent rules = `2` - `VRMS_IMB`/`IRMS_IMB`/`PF_IMB`).
+
+**Two real bugs found and fixed live while backfilling those priorities**: `Schema.Synthesis_Variable_Schema.Priority` defaulted to `1` and `.Status` defaulted to `False` (neither `None`) - `update()`'s partial-update logic treats any non-`None` value as "change this," so a Priority-only update silently reset every rule's `Status` to `False` (caught immediately: "kanka bu arada status false yapmışsın"). Fixed both defaults to `None`. A follow-up Status-only fix then *appeared* to reset every `Priority` back to `1` when read through the CLI - that one turned out to be a stale Redis cache read, not a third instance of the bug (a raw DB query confirmed `Priority` was correct throughout; `get_list(update=True)` fixed the CLI's view) - worth remembering that this system's live pipeline (`services/data`, evaluating rules on every real packet) reads through the same cache, so hand-editing rows can produce a confusing stale-vs-real mismatch mid-edit. Final state verified three ways (raw DB, forced cache refresh, CLI): all 9 rules `Status=True`, correct `Priority` split (6×`1`, 3×`2`).
+
+**(From the original 2026-09-02 read-only version)** `synthesis list` supports `--device-id`/`--variable-id`/`--active`/`--inactive` filters. A real CLI bug was caught while first testing it: `Calculation` is a JSON object (e.g. `{"formula": "(VRMS_R + VRMS_S + VRMS_T) / 3"}`), not a string - the table crashed with `NotRenderableError: unable to render dict` until values were `json.dumps()`-ed before being handed to the table row.
+
 **`project` (added 2026-09-02) is full read/write**, per an analyst-workflow review of the CLI ("Cinga ve diğer ürün/aile ayrımlarında proje bazlı gezinme lazım") - `Project` (`common/qapu_common/domain/project.py`) already had full CRUD (list/detail/add/update/delete) with zero Hermes/CLI wiring at all until now, same "remaining domain, wire it up" pattern as every other catalog this session. Same low-sensitivity reasoning as `group`/`manufacturer`/`calibration`: a plain project catalog (Cinga/WeatherStat/...), no device actuation, no financial/PII. `project devices <project_id>` returns full device detail (not just IDs, unlike `group devices`) via `Device.list(project_id=...)`, which already existed and already returns the full `Device_Detail_Schema` shape - more useful for an analyst than a bare ID list. Live-tested against real prod data: `project list` correctly showed the one real active project (`Cinga V1`, `id=1` - the `id=0` "Unknown" row is deliberately excluded by `Project.list()` itself); `project devices 1 --limit 3` correctly showed 3 real devices; a full add→get(confirm)→update(confirm)→delete→get(404) cycle on a disposable test project, the real `Cinga V1` row never touched.
 
 ```bash
@@ -247,8 +264,6 @@ These six catalogs (`manufacturer`/`model`/`modem`/`sim`/`firmware`/`status`) pl
 
 **`stream get`'s detail was extended the same day**, per user request: `Command_ID` (a bare FK integer, not meaningful on its own) is now resolved and returned as `Command_Name` instead (via `qapu_common.domain.command.Command.detail()`); a new `Variable_Count` field reports how many variables `Stream.get_stream_measurements()` actually recorded from that packet - not previously visible from `stream get` at all. `Size` is now rendered as e.g. `418 byte` in both `stream get` and `stream list`'s table (the raw `--json` output stays a plain int, only the human-readable rendering changed). The Hermes endpoint's `response_model` was dropped to `None` for this route specifically, since the response shape now deliberately diverges from the underlying `Stream_Schema` (swapped field, added field) - every other Hermes route keeps its typed `response_model`, this is a one-off. Live-tested against real prod data: `stream get 4879335` correctly showed `Command_Name: Timed` and `Variable_Count: 18`.
 
-**`synthesis` (added 2026-09-02) is read-only, `list` only** - `synthesis_variable_rules` (how a derived metric like `VRMS_A`/`AE_TOT`/power-factor-imbalance gets calculated from raw variables) has no `add()`/`update()`/`delete()` on the domain class at all, it's a small, directly-DB-managed rule set. `Device_ID='0'` rows are global (applied to every device); a real device ID scopes a rule to just that device. `synthesis list` supports `--device-id`/`--variable-id`/`--active`/`--inactive` filters, showing ID/Device/Variable/Priority/Required Variables/Calculation/Active in a table. **Real CLI bug found and fixed while testing this**: `Calculation` is a JSON object (the actual formula, e.g. `{"formula": "(VRMS_R + VRMS_S + VRMS_T) / 3"}`), not a string - the first version of this table crashed with `NotRenderableError: unable to render dict` the moment it hit a real row; fixed by `json.dumps()`-ing dict values before handing them to the table. Live-tested against real prod data after the fix: all 12 real global synthesis rules rendered correctly (readable formulas), `--active`/`--variable-id` filters both confirmed correct counts.
-
 **`user-role` (added 2026-09-02) is the ONLY piece of the `user` domain wired up here, and deliberately so** - the user was asked explicitly first, since `user`/`finance` had been excluded from this router since it was first built (a leaked `QAPU_HERMES_KEY` - a shared secret, not real per-admin JWT - must never expose PII or financial data). Chose "read-only, PII-free fields only" as the safe subset: `User_Role` (`common/qapu_common/domain/user.py`) is a plain ID/Name/Description role catalog (admin/farmer/technician/...) with zero PII, structurally identical to `crop-type`/`pump-type`. The actual `User` class (name/phone/email) and `Authorization` (which user owns which device) are NOT wired up and were never considered - PII and device-ownership data stay off this router entirely, same as `finance`.
 - **Real bug found and fixed while testing this**: `User_Role.add()` requires an explicit `ID` - unlike `Status` (which falls back to auto-increment when `ID` is omitted), `user_roles.id` is not an auto-increment column at all (`Column(Integer, primary_key=True, nullable=False)`, no `autoincrement`). The first CLI version only took `Name`/`--description`, so every `add` failed with a misleading `"User role Name is required"` (Name *was* provided - `ID` was the actual missing field). Fixed by making `id` a required positional argument on `user-role add` and clarifying the Hermes error message. Live-tested end to end against real prod data (10 real roles - admin/supervisor/technician/field_technician/accountant/dealer/farmer/farmer_employee/farmer_electrician/demo_user, confirmed zero PII, none touched): a full add(explicit ID `999`)→get→update→get(confirm)→delete→get(404) cycle on a disposable row.
 

{qapu_cli-0.6.2 → qapu_cli-0.6.4}/README.md

@@ -170,7 +170,10 @@ qapu stream list <device_id> [--page N] [--size N] [--json]   # GET /hermes/stre
 qapu stream get <stream_id>                                     # GET /hermes/stream/detail/{stream_id}
 
 qapu synthesis list [--device-id] [--variable-id] [--active/--inactive] [--json]   # GET /hermes/synthesis - derived-metric calculation rules
-
+qapu synthesis get <rule_id> [--json]                                             # GET /hermes/synthesis/{rule_id}
+qapu synthesis add <variable_id> --required-variables A,B,C --calculation '{"formula": "A + B"}' [--device-id] [--conditions] [--min-value] [--max-value] [--priority] [--active/--inactive] [--description]  # POST /hermes/synthesis
+qapu synthesis update <rule_id> [--variable-id] [--required-variables] [--calculation] [--device-id] [--conditions] [--min-value] [--max-value] [--priority] [--active/--inactive] [--description]  # PUT /hermes/synthesis/{rule_id}
+qapu synthesis delete <rule_id>                                                    # DELETE /hermes/synthesis/{rule_id}
 qapu user-role list [--json] [--limit N]                # GET /hermes/user_roles - e.g. admin/farmer/technician, NOT the User class itself (PII, deliberately excluded)
 qapu user-role get <role_id> [--json]                    # GET /hermes/user_roles/{id}
 qapu user-role add <id> "Name" [--description]           # POST /hermes/user_roles - ID is REQUIRED, this catalog's ID is NOT auto-increment
@@ -188,6 +191,20 @@ qapu project update <project_id> [--name] [--description] [--active/--inactive]
 qapu project delete <project_id>                               # DELETE /hermes/projects/{project_id}
 ```
 
+**`synthesis` extended to full CRUD (2026-09-03)**, per direct user correction after the read-only version shipped the day before ("qapu synthesis için tam crud yapmamışsın sadece list var"). The 2026-09-02 read-only version was a faithful reflection of the domain class at the time - `Synthesized_Metrics` genuinely had no `add()`/`update()`/`delete()`, only `get_list()`. Added `detail()`/`add()`/`update()`/`delete()` to `common/qapu_common/domain/synthesized_metrics.py` (following the same partial-update/cache-invalidation pattern every other domain class in this session uses), then wired all four into `services/api/src/routers/hermes.py` and the CLI. `--required-variables`/`--conditions` take comma-separated/JSON-string input respectively (`Required_Variables` is a plain list, `Conditions`/`Calculation` are JSON columns) - `--calculation`/`--conditions` are validated as JSON client-side before the request goes out, with a clear error instead of a confusing 400 from the API. New unit tests in `common/tests/test_synthesized_metrics.py` (detail/add/update/delete, 10 new cases) - 502 tests passing.
+
+**Two real production findings surfaced while live-testing this, neither a bug in the new code, both since resolved (see CLAUDE.md's 2026-09-03 entries for the full incident/recovery detail)**:
+1. **`synthesis_variable_rules` turned out to be completely empty in production at the time** - `qapu synthesis list` had been showing 12 rules, but that was a stale Redis cache with nothing backing it in the actual table. Force-refreshing that cache to verify the DB state (`Synthesized_Metrics().get_list(update=True)`) deleted the cache key without anything to refill it from, since the DB read came back empty - and since `synthesize_measurements()` (`common/qapu_common/domain/measurement.py`, called on every real device packet by `services/data`) reads through that same cache, this briefly took real, actively-used synthesis logic out of production, not just cleared a harmless stale copy. **Recovered same day**: the user pulled a dump of the equivalent table from the legacy monolith's own (separate, pre-migration) database via pgAdmin and handed over 9 real rule definitions (weather-related ones deliberately excluded), re-inserted via `Synthesized_Metrics().add()` - formulas/required-variables/conditions/min-max/description preserved verbatim. A real ordering bug surfaced in the restored data itself (not caused by the restore) - `PF_IMB` depends on `PF_AVG` but was ID-ordered before it in the legacy dump, so it was silently skipped every evaluation; fixed by re-inserting `PF_AVG` before `PF_IMB` so ID order matches the dependency. All 9 rules verified correct via a real `calculate_synthesized_metrics()` run.
+2. **A "global" rule (`Device_ID="0"`, applied to every device) could not be added at all** - `synthesis_variable_rules.device_id` is a foreign key into `devices.id`, and there was no `id='0'` placeholder row in `devices` (unlike `projects`/`statuses`, which do have a real `id=0` "Unknown" row). **Fixed same day, per explicit user request**: added `devices.id='0'` ("Unknown Device", `Status_ID`/`Project_ID` both `0`, both already real "Unknown" rows) via `Device().add()`; `Device.list()` (`common/qapu_common/domain/device.py`) updated to exclude `id="0"` (same exclusion `Project.list()` already applies to its own Unknown row) so this placeholder never appears in `qapu device list`/`GET /hermes/devices` as if it were a real device.
+
+Live-tested against real prod data throughout: the original add→get→update→delete→get(404) cycle on a disposable rule (before the empty-table discovery); the 9-rule restore verified both via `synthesis list` and a real `calculate_synthesized_metrics()` computation; `device list` confirmed to still show exactly 11 real devices, `"0"` excluded.
+
+**`--priority` added the same day, per direct user request** ("priority sırasını sen hesaplanacak verilere göre düzenle") - rules are evaluated in `(Priority, ID)` order, and a rule can only see another rule's output if that rule already ran, so relying on insertion (ID) order alone is fragile. `synthesis_variable_rules.priority` turned out to already be a real DB column (`integer NOT NULL DEFAULT 1`) that `common/qapu_common/database/models.py`'s ORM model simply never declared - `get_list()` had been hardcoding `Priority=1` the whole time rather than reading it. Fixed by adding the column to the model; `get_list()`/`add()`/`update()` now read/write it for real. The 9 restored rules were backfilled with real values (independent rules = `1`, one-level-dependent rules = `2` - `VRMS_IMB`/`IRMS_IMB`/`PF_IMB`).
+
+**Two real bugs found and fixed live while backfilling those priorities**: `Schema.Synthesis_Variable_Schema.Priority` defaulted to `1` and `.Status` defaulted to `False` (neither `None`) - `update()`'s partial-update logic treats any non-`None` value as "change this," so a Priority-only update silently reset every rule's `Status` to `False` (caught immediately: "kanka bu arada status false yapmışsın"). Fixed both defaults to `None`. A follow-up Status-only fix then *appeared* to reset every `Priority` back to `1` when read through the CLI - that one turned out to be a stale Redis cache read, not a third instance of the bug (a raw DB query confirmed `Priority` was correct throughout; `get_list(update=True)` fixed the CLI's view) - worth remembering that this system's live pipeline (`services/data`, evaluating rules on every real packet) reads through the same cache, so hand-editing rows can produce a confusing stale-vs-real mismatch mid-edit. Final state verified three ways (raw DB, forced cache refresh, CLI): all 9 rules `Status=True`, correct `Priority` split (6×`1`, 3×`2`).
+
+**(From the original 2026-09-02 read-only version)** `synthesis list` supports `--device-id`/`--variable-id`/`--active`/`--inactive` filters. A real CLI bug was caught while first testing it: `Calculation` is a JSON object (e.g. `{"formula": "(VRMS_R + VRMS_S + VRMS_T) / 3"}`), not a string - the table crashed with `NotRenderableError: unable to render dict` until values were `json.dumps()`-ed before being handed to the table row.
+
 **`project` (added 2026-09-02) is full read/write**, per an analyst-workflow review of the CLI ("Cinga ve diğer ürün/aile ayrımlarında proje bazlı gezinme lazım") - `Project` (`common/qapu_common/domain/project.py`) already had full CRUD (list/detail/add/update/delete) with zero Hermes/CLI wiring at all until now, same "remaining domain, wire it up" pattern as every other catalog this session. Same low-sensitivity reasoning as `group`/`manufacturer`/`calibration`: a plain project catalog (Cinga/WeatherStat/...), no device actuation, no financial/PII. `project devices <project_id>` returns full device detail (not just IDs, unlike `group devices`) via `Device.list(project_id=...)`, which already existed and already returns the full `Device_Detail_Schema` shape - more useful for an analyst than a bare ID list. Live-tested against real prod data: `project list` correctly showed the one real active project (`Cinga V1`, `id=1` - the `id=0` "Unknown" row is deliberately excluded by `Project.list()` itself); `project devices 1 --limit 3` correctly showed 3 real devices; a full add→get(confirm)→update(confirm)→delete→get(404) cycle on a disposable test project, the real `Cinga V1` row never touched.
 
 ```bash
@@ -235,8 +252,6 @@ These six catalogs (`manufacturer`/`model`/`modem`/`sim`/`firmware`/`status`) pl
 
 **`stream get`'s detail was extended the same day**, per user request: `Command_ID` (a bare FK integer, not meaningful on its own) is now resolved and returned as `Command_Name` instead (via `qapu_common.domain.command.Command.detail()`); a new `Variable_Count` field reports how many variables `Stream.get_stream_measurements()` actually recorded from that packet - not previously visible from `stream get` at all. `Size` is now rendered as e.g. `418 byte` in both `stream get` and `stream list`'s table (the raw `--json` output stays a plain int, only the human-readable rendering changed). The Hermes endpoint's `response_model` was dropped to `None` for this route specifically, since the response shape now deliberately diverges from the underlying `Stream_Schema` (swapped field, added field) - every other Hermes route keeps its typed `response_model`, this is a one-off. Live-tested against real prod data: `stream get 4879335` correctly showed `Command_Name: Timed` and `Variable_Count: 18`.
 
-**`synthesis` (added 2026-09-02) is read-only, `list` only** - `synthesis_variable_rules` (how a derived metric like `VRMS_A`/`AE_TOT`/power-factor-imbalance gets calculated from raw variables) has no `add()`/`update()`/`delete()` on the domain class at all, it's a small, directly-DB-managed rule set. `Device_ID='0'` rows are global (applied to every device); a real device ID scopes a rule to just that device. `synthesis list` supports `--device-id`/`--variable-id`/`--active`/`--inactive` filters, showing ID/Device/Variable/Priority/Required Variables/Calculation/Active in a table. **Real CLI bug found and fixed while testing this**: `Calculation` is a JSON object (the actual formula, e.g. `{"formula": "(VRMS_R + VRMS_S + VRMS_T) / 3"}`), not a string - the first version of this table crashed with `NotRenderableError: unable to render dict` the moment it hit a real row; fixed by `json.dumps()`-ing dict values before handing them to the table. Live-tested against real prod data after the fix: all 12 real global synthesis rules rendered correctly (readable formulas), `--active`/`--variable-id` filters both confirmed correct counts.
-
 **`user-role` (added 2026-09-02) is the ONLY piece of the `user` domain wired up here, and deliberately so** - the user was asked explicitly first, since `user`/`finance` had been excluded from this router since it was first built (a leaked `QAPU_HERMES_KEY` - a shared secret, not real per-admin JWT - must never expose PII or financial data). Chose "read-only, PII-free fields only" as the safe subset: `User_Role` (`common/qapu_common/domain/user.py`) is a plain ID/Name/Description role catalog (admin/farmer/technician/...) with zero PII, structurally identical to `crop-type`/`pump-type`. The actual `User` class (name/phone/email) and `Authorization` (which user owns which device) are NOT wired up and were never considered - PII and device-ownership data stay off this router entirely, same as `finance`.
 - **Real bug found and fixed while testing this**: `User_Role.add()` requires an explicit `ID` - unlike `Status` (which falls back to auto-increment when `ID` is omitted), `user_roles.id` is not an auto-increment column at all (`Column(Integer, primary_key=True, nullable=False)`, no `autoincrement`). The first CLI version only took `Name`/`--description`, so every `add` failed with a misleading `"User role Name is required"` (Name *was* provided - `ID` was the actual missing field). Fixed by making `id` a required positional argument on `user-role add` and clarifying the Hermes error message. Live-tested end to end against real prod data (10 real roles - admin/supervisor/technician/field_technician/accountant/dealer/farmer/farmer_employee/farmer_electrician/demo_user, confirmed zero PII, none touched): a full add(explicit ID `999`)→get→update→get(confirm)→delete→get(404) cycle on a disposable row.
 

{qapu_cli-0.6.2 → qapu_cli-0.6.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qapu-cli"
-version = "0.6.2"
+version = "0.6.4"
 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.6.2 → qapu_cli-0.6.4}/qapu_cli/main.py

@@ -2689,6 +2689,126 @@ def synthesis_list(
 	console.print(table)
 
 
+# Get One Synthesis Rule's Detail
+@synthesis_app.command("get")
+def synthesis_get(rule_id: int = typer.Argument(...), as_json: bool = typer.Option(False, "--json")):
+	"""Get one synthesis rule's detail (GET /hermes/synthesis/{rule_id})."""
+	result = client.get(f"/hermes/synthesis/{rule_id}")
+	if as_json:
+		typer.echo(json.dumps(result, indent=2))
+		return
+	_print_detail(result)
+
+
+# Add a New Synthesis Rule
+@synthesis_app.command("add")
+def synthesis_add(
+	variable_id: str = typer.Argument(..., help="Variable ID this rule calculates, e.g. 'P_TOT'."),
+	required_variables: str = typer.Option(..., "--required-variables", help="Comma-separated list of variables the formula needs, e.g. P_R,P_S,P_T."),
+	calculation: str = typer.Option(..., "--calculation", help='Calculation formula as JSON, e.g. \'{"formula": "P_R + P_S"}\'.'),
+	device_id: Optional[str] = typer.Option(None, "--device-id", help="Scope to one device instead of every device (default: global, Device_ID='0')."),
+	conditions: Optional[str] = typer.Option(None, "--conditions", help='Conditions as a JSON list, e.g. \'[{"Variable":"X","Condition":">","Value":5}]\'.'),
+	min_value: Optional[float] = typer.Option(None, "--min-value"),
+	max_value: Optional[float] = typer.Option(None, "--max-value"),
+	priority: int = typer.Option(1, "--priority", help="Evaluation order - lower runs first. Must be higher than any rule this one depends on via --required-variables, or that dependency won't be computed yet when this one runs."),
+	active: bool = typer.Option(False, "--active/--inactive"),
+	description: Optional[str] = typer.Option(None, "--description"),
+):
+	"""Create a new synthesis rule (POST /hermes/synthesis)."""
+	try:
+		calculation_data = json.loads(calculation)
+	except json.JSONDecodeError:
+		typer.echo("Error: --calculation must be valid JSON.", err=True)
+		raise typer.Exit(code=1)
+	conditions_data = None
+	if conditions is not None:
+		try:
+			conditions_data = json.loads(conditions)
+		except json.JSONDecodeError:
+			typer.echo("Error: --conditions must be valid JSON.", err=True)
+			raise typer.Exit(code=1)
+	body: dict[str, Any] = {
+		"Variable_ID": variable_id,
+		"Required_Variables": [v.strip() for v in required_variables.split(",") if v.strip()],
+		"Calculation": calculation_data,
+		"Status": active,
+	}
+	if device_id is not None:
+		body["Device_ID"] = device_id
+	if conditions_data is not None:
+		body["Conditions"] = conditions_data
+	if min_value is not None:
+		body["Minimum_Value"] = min_value
+	if max_value is not None:
+		body["Maximum_Value"] = max_value
+	if priority is not None:
+		body["Priority"] = priority
+	if description is not None:
+		body["Description"] = description
+	result = client.post("/hermes/synthesis", json_body=body)
+	typer.echo(result.get("Message", result))
+
+
+# Update an Existing Synthesis Rule
+@synthesis_app.command("update")
+def synthesis_update(
+	rule_id: int = typer.Argument(...),
+	variable_id: Optional[str] = typer.Option(None, "--variable-id"),
+	required_variables: Optional[str] = typer.Option(None, "--required-variables", help="Comma-separated list, replaces the existing list entirely."),
+	calculation: Optional[str] = typer.Option(None, "--calculation", help='Calculation formula as JSON, e.g. \'{"formula": "P_R + P_S"}\'.'),
+	device_id: Optional[str] = typer.Option(None, "--device-id"),
+	conditions: Optional[str] = typer.Option(None, "--conditions", help="Conditions as a JSON list, replaces the existing list entirely."),
+	min_value: Optional[float] = typer.Option(None, "--min-value"),
+	max_value: Optional[float] = typer.Option(None, "--max-value"),
+	priority: Optional[int] = typer.Option(None, "--priority", help="Evaluation order - lower runs first."),
+	active: Optional[bool] = typer.Option(None, "--active/--inactive"),
+	description: Optional[str] = typer.Option(None, "--description"),
+):
+	"""Update an existing synthesis rule - only the fields passed are changed (PUT /hermes/synthesis/{rule_id})."""
+	body: dict[str, Any] = {}
+	if variable_id is not None:
+		body["Variable_ID"] = variable_id
+	if required_variables is not None:
+		body["Required_Variables"] = [v.strip() for v in required_variables.split(",") if v.strip()]
+	if calculation is not None:
+		try:
+			body["Calculation"] = json.loads(calculation)
+		except json.JSONDecodeError:
+			typer.echo("Error: --calculation must be valid JSON.", err=True)
+			raise typer.Exit(code=1)
+	if device_id is not None:
+		body["Device_ID"] = device_id
+	if conditions is not None:
+		try:
+			body["Conditions"] = json.loads(conditions)
+		except json.JSONDecodeError:
+			typer.echo("Error: --conditions must be valid JSON.", err=True)
+			raise typer.Exit(code=1)
+	if min_value is not None:
+		body["Minimum_Value"] = min_value
+	if max_value is not None:
+		body["Maximum_Value"] = max_value
+	if priority is not None:
+		body["Priority"] = priority
+	if active is not None:
+		body["Status"] = active
+	if description is not None:
+		body["Description"] = description
+	if not body:
+		typer.echo("Error: nothing to update - pass at least one field.", err=True)
+		raise typer.Exit(code=1)
+	result = client.put(f"/hermes/synthesis/{rule_id}", json_body=body)
+	typer.echo(result.get("Message", result))
+
+
+# Delete an Existing Synthesis Rule
+@synthesis_app.command("delete")
+def synthesis_delete(rule_id: int = typer.Argument(...)):
+	"""Delete an existing synthesis rule (DELETE /hermes/synthesis/{rule_id})."""
+	result = client.delete(f"/hermes/synthesis/{rule_id}")
+	typer.echo(result.get("Message", result))
+
+
 # List User Roles
 @user_role_app.command("list")
 def user_role_list(as_json: bool = typer.Option(False, "--json"), limit: Optional[int] = typer.Option(None, "--limit")):

{qapu_cli-0.6.2 → qapu_cli-0.6.4}/qapu_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qapu-cli
-Version: 0.6.2
+Version: 0.6.4
 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
@@ -182,7 +182,10 @@ qapu stream list <device_id> [--page N] [--size N] [--json]   # GET /hermes/stre
 qapu stream get <stream_id>                                     # GET /hermes/stream/detail/{stream_id}
 
 qapu synthesis list [--device-id] [--variable-id] [--active/--inactive] [--json]   # GET /hermes/synthesis - derived-metric calculation rules
-
+qapu synthesis get <rule_id> [--json]                                             # GET /hermes/synthesis/{rule_id}
+qapu synthesis add <variable_id> --required-variables A,B,C --calculation '{"formula": "A + B"}' [--device-id] [--conditions] [--min-value] [--max-value] [--priority] [--active/--inactive] [--description]  # POST /hermes/synthesis
+qapu synthesis update <rule_id> [--variable-id] [--required-variables] [--calculation] [--device-id] [--conditions] [--min-value] [--max-value] [--priority] [--active/--inactive] [--description]  # PUT /hermes/synthesis/{rule_id}
+qapu synthesis delete <rule_id>                                                    # DELETE /hermes/synthesis/{rule_id}
 qapu user-role list [--json] [--limit N]                # GET /hermes/user_roles - e.g. admin/farmer/technician, NOT the User class itself (PII, deliberately excluded)
 qapu user-role get <role_id> [--json]                    # GET /hermes/user_roles/{id}
 qapu user-role add <id> "Name" [--description]           # POST /hermes/user_roles - ID is REQUIRED, this catalog's ID is NOT auto-increment
@@ -200,6 +203,20 @@ qapu project update <project_id> [--name] [--description] [--active/--inactive]
 qapu project delete <project_id>                               # DELETE /hermes/projects/{project_id}
 ```
 
+**`synthesis` extended to full CRUD (2026-09-03)**, per direct user correction after the read-only version shipped the day before ("qapu synthesis için tam crud yapmamışsın sadece list var"). The 2026-09-02 read-only version was a faithful reflection of the domain class at the time - `Synthesized_Metrics` genuinely had no `add()`/`update()`/`delete()`, only `get_list()`. Added `detail()`/`add()`/`update()`/`delete()` to `common/qapu_common/domain/synthesized_metrics.py` (following the same partial-update/cache-invalidation pattern every other domain class in this session uses), then wired all four into `services/api/src/routers/hermes.py` and the CLI. `--required-variables`/`--conditions` take comma-separated/JSON-string input respectively (`Required_Variables` is a plain list, `Conditions`/`Calculation` are JSON columns) - `--calculation`/`--conditions` are validated as JSON client-side before the request goes out, with a clear error instead of a confusing 400 from the API. New unit tests in `common/tests/test_synthesized_metrics.py` (detail/add/update/delete, 10 new cases) - 502 tests passing.
+
+**Two real production findings surfaced while live-testing this, neither a bug in the new code, both since resolved (see CLAUDE.md's 2026-09-03 entries for the full incident/recovery detail)**:
+1. **`synthesis_variable_rules` turned out to be completely empty in production at the time** - `qapu synthesis list` had been showing 12 rules, but that was a stale Redis cache with nothing backing it in the actual table. Force-refreshing that cache to verify the DB state (`Synthesized_Metrics().get_list(update=True)`) deleted the cache key without anything to refill it from, since the DB read came back empty - and since `synthesize_measurements()` (`common/qapu_common/domain/measurement.py`, called on every real device packet by `services/data`) reads through that same cache, this briefly took real, actively-used synthesis logic out of production, not just cleared a harmless stale copy. **Recovered same day**: the user pulled a dump of the equivalent table from the legacy monolith's own (separate, pre-migration) database via pgAdmin and handed over 9 real rule definitions (weather-related ones deliberately excluded), re-inserted via `Synthesized_Metrics().add()` - formulas/required-variables/conditions/min-max/description preserved verbatim. A real ordering bug surfaced in the restored data itself (not caused by the restore) - `PF_IMB` depends on `PF_AVG` but was ID-ordered before it in the legacy dump, so it was silently skipped every evaluation; fixed by re-inserting `PF_AVG` before `PF_IMB` so ID order matches the dependency. All 9 rules verified correct via a real `calculate_synthesized_metrics()` run.
+2. **A "global" rule (`Device_ID="0"`, applied to every device) could not be added at all** - `synthesis_variable_rules.device_id` is a foreign key into `devices.id`, and there was no `id='0'` placeholder row in `devices` (unlike `projects`/`statuses`, which do have a real `id=0` "Unknown" row). **Fixed same day, per explicit user request**: added `devices.id='0'` ("Unknown Device", `Status_ID`/`Project_ID` both `0`, both already real "Unknown" rows) via `Device().add()`; `Device.list()` (`common/qapu_common/domain/device.py`) updated to exclude `id="0"` (same exclusion `Project.list()` already applies to its own Unknown row) so this placeholder never appears in `qapu device list`/`GET /hermes/devices` as if it were a real device.
+
+Live-tested against real prod data throughout: the original add→get→update→delete→get(404) cycle on a disposable rule (before the empty-table discovery); the 9-rule restore verified both via `synthesis list` and a real `calculate_synthesized_metrics()` computation; `device list` confirmed to still show exactly 11 real devices, `"0"` excluded.
+
+**`--priority` added the same day, per direct user request** ("priority sırasını sen hesaplanacak verilere göre düzenle") - rules are evaluated in `(Priority, ID)` order, and a rule can only see another rule's output if that rule already ran, so relying on insertion (ID) order alone is fragile. `synthesis_variable_rules.priority` turned out to already be a real DB column (`integer NOT NULL DEFAULT 1`) that `common/qapu_common/database/models.py`'s ORM model simply never declared - `get_list()` had been hardcoding `Priority=1` the whole time rather than reading it. Fixed by adding the column to the model; `get_list()`/`add()`/`update()` now read/write it for real. The 9 restored rules were backfilled with real values (independent rules = `1`, one-level-dependent rules = `2` - `VRMS_IMB`/`IRMS_IMB`/`PF_IMB`).
+
+**Two real bugs found and fixed live while backfilling those priorities**: `Schema.Synthesis_Variable_Schema.Priority` defaulted to `1` and `.Status` defaulted to `False` (neither `None`) - `update()`'s partial-update logic treats any non-`None` value as "change this," so a Priority-only update silently reset every rule's `Status` to `False` (caught immediately: "kanka bu arada status false yapmışsın"). Fixed both defaults to `None`. A follow-up Status-only fix then *appeared* to reset every `Priority` back to `1` when read through the CLI - that one turned out to be a stale Redis cache read, not a third instance of the bug (a raw DB query confirmed `Priority` was correct throughout; `get_list(update=True)` fixed the CLI's view) - worth remembering that this system's live pipeline (`services/data`, evaluating rules on every real packet) reads through the same cache, so hand-editing rows can produce a confusing stale-vs-real mismatch mid-edit. Final state verified three ways (raw DB, forced cache refresh, CLI): all 9 rules `Status=True`, correct `Priority` split (6×`1`, 3×`2`).
+
+**(From the original 2026-09-02 read-only version)** `synthesis list` supports `--device-id`/`--variable-id`/`--active`/`--inactive` filters. A real CLI bug was caught while first testing it: `Calculation` is a JSON object (e.g. `{"formula": "(VRMS_R + VRMS_S + VRMS_T) / 3"}`), not a string - the table crashed with `NotRenderableError: unable to render dict` until values were `json.dumps()`-ed before being handed to the table row.
+
 **`project` (added 2026-09-02) is full read/write**, per an analyst-workflow review of the CLI ("Cinga ve diğer ürün/aile ayrımlarında proje bazlı gezinme lazım") - `Project` (`common/qapu_common/domain/project.py`) already had full CRUD (list/detail/add/update/delete) with zero Hermes/CLI wiring at all until now, same "remaining domain, wire it up" pattern as every other catalog this session. Same low-sensitivity reasoning as `group`/`manufacturer`/`calibration`: a plain project catalog (Cinga/WeatherStat/...), no device actuation, no financial/PII. `project devices <project_id>` returns full device detail (not just IDs, unlike `group devices`) via `Device.list(project_id=...)`, which already existed and already returns the full `Device_Detail_Schema` shape - more useful for an analyst than a bare ID list. Live-tested against real prod data: `project list` correctly showed the one real active project (`Cinga V1`, `id=1` - the `id=0` "Unknown" row is deliberately excluded by `Project.list()` itself); `project devices 1 --limit 3` correctly showed 3 real devices; a full add→get(confirm)→update(confirm)→delete→get(404) cycle on a disposable test project, the real `Cinga V1` row never touched.
 
 ```bash
@@ -247,8 +264,6 @@ These six catalogs (`manufacturer`/`model`/`modem`/`sim`/`firmware`/`status`) pl
 
 **`stream get`'s detail was extended the same day**, per user request: `Command_ID` (a bare FK integer, not meaningful on its own) is now resolved and returned as `Command_Name` instead (via `qapu_common.domain.command.Command.detail()`); a new `Variable_Count` field reports how many variables `Stream.get_stream_measurements()` actually recorded from that packet - not previously visible from `stream get` at all. `Size` is now rendered as e.g. `418 byte` in both `stream get` and `stream list`'s table (the raw `--json` output stays a plain int, only the human-readable rendering changed). The Hermes endpoint's `response_model` was dropped to `None` for this route specifically, since the response shape now deliberately diverges from the underlying `Stream_Schema` (swapped field, added field) - every other Hermes route keeps its typed `response_model`, this is a one-off. Live-tested against real prod data: `stream get 4879335` correctly showed `Command_Name: Timed` and `Variable_Count: 18`.
 
-**`synthesis` (added 2026-09-02) is read-only, `list` only** - `synthesis_variable_rules` (how a derived metric like `VRMS_A`/`AE_TOT`/power-factor-imbalance gets calculated from raw variables) has no `add()`/`update()`/`delete()` on the domain class at all, it's a small, directly-DB-managed rule set. `Device_ID='0'` rows are global (applied to every device); a real device ID scopes a rule to just that device. `synthesis list` supports `--device-id`/`--variable-id`/`--active`/`--inactive` filters, showing ID/Device/Variable/Priority/Required Variables/Calculation/Active in a table. **Real CLI bug found and fixed while testing this**: `Calculation` is a JSON object (the actual formula, e.g. `{"formula": "(VRMS_R + VRMS_S + VRMS_T) / 3"}`), not a string - the first version of this table crashed with `NotRenderableError: unable to render dict` the moment it hit a real row; fixed by `json.dumps()`-ing dict values before handing them to the table. Live-tested against real prod data after the fix: all 12 real global synthesis rules rendered correctly (readable formulas), `--active`/`--variable-id` filters both confirmed correct counts.
-
 **`user-role` (added 2026-09-02) is the ONLY piece of the `user` domain wired up here, and deliberately so** - the user was asked explicitly first, since `user`/`finance` had been excluded from this router since it was first built (a leaked `QAPU_HERMES_KEY` - a shared secret, not real per-admin JWT - must never expose PII or financial data). Chose "read-only, PII-free fields only" as the safe subset: `User_Role` (`common/qapu_common/domain/user.py`) is a plain ID/Name/Description role catalog (admin/farmer/technician/...) with zero PII, structurally identical to `crop-type`/`pump-type`. The actual `User` class (name/phone/email) and `Authorization` (which user owns which device) are NOT wired up and were never considered - PII and device-ownership data stay off this router entirely, same as `finance`.
 - **Real bug found and fixed while testing this**: `User_Role.add()` requires an explicit `ID` - unlike `Status` (which falls back to auto-increment when `ID` is omitted), `user_roles.id` is not an auto-increment column at all (`Column(Integer, primary_key=True, nullable=False)`, no `autoincrement`). The first CLI version only took `Name`/`--description`, so every `add` failed with a misleading `"User role Name is required"` (Name *was* provided - `ID` was the actual missing field). Fixed by making `id` a required positional argument on `user-role add` and clarifying the Hermes error message. Live-tested end to end against real prod data (10 real roles - admin/supervisor/technician/field_technician/accountant/dealer/farmer/farmer_employee/farmer_electrician/demo_user, confirmed zero PII, none touched): a full add(explicit ID `999`)→get→update→get(confirm)→delete→get(404) cycle on a disposable row.