unique-user-memory 2026.38.0.dev2__tar.gz → 2026.40.0.dev0__tar.gz

unique_user_memory-2026.38.0.dev2/README.md → unique_user_memory-2026.40.0.dev0/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.3
+Name: unique-user-memory
+Version: 2026.40.0.dev0
+Summary: 
+Author: Fabian Schläpfer
+Author-email: Fabian Schläpfer <fabian@unique.ch>
+License: Proprietary
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pydantic>=2.8.2
+Requires-Dist: unique-sdk>=2026.40.0.dev0,<2026.40.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.40.0.dev0,<2026.40.0rc0
+Requires-Python: >=3.12, <4
+Description-Content-Type: text/markdown
+
 # Unique User Memory
 
 Persistent per-user memory for Unique AI agents.
@@ -130,6 +144,27 @@ config = UserMemoryConfig(
 | `max_tokens` | `2000` | Maximum profile size. Must be between 500 and 8000 tokens. |
 | `root_folder` | `user-memory` | Subfolder name under each user's home folder (`/home-<user_id>/<root_folder>`) that holds the memory profile; also read as a legacy fallback at `/<root_folder>/<user_id>`. |
 
+## Observability
+
+The package registers Prometheus metrics on the shared `unique_toolkit.monitoring` registry (namespace `unique_user_memory`). They appear on whatever host already scrapes `GET /metrics` (assistants-core). Labels are closed enums — no company or user ids. LLM series include the model name so latency can be split per deployed model.
+
+QA dashboard: [User Memory](https://qa-grafana.alpine-bowfin.ts.net/d/unique-user-memory) (`unique-user-memory`). The dashboard is provisioned by the [assistants-core Helm chart](https://github.com/Unique-AG/monorepo/tree/master/python/assistants/bundles/core/deploy/helm-chart/files/grafana/dashboards).
+
+| Metric | Labels | What it answers |
+| --- | --- | --- |
+| `load_duration_seconds` / `load_total` | `outcome`: `success`, `empty`, `folder_failed`, `skipped_no_ids` | Is load slow? How often do we run without memory? |
+| `postprocessor_duration_seconds` / `postprocessor_total` | `outcome`: `updated`, `noop`, `upload_failed`, `skipped_no_ids`, `error` | Did this turn persist a new profile? |
+| `errors_total` | `stage`, `error_type` | Infra failures by stage (`folder_lookup`, `folder_create`, `download`, `upload`, `gate`, `consolidation`, `scrub`, `condense`, `postprocessor`). |
+| `llm_duration_seconds` / `llm_errors_total` | `purpose`: `gate`, `consolidation`, `scrub`, `condense`; `model`: the configured model name | Which LLM call is the latency or error hog, and how does that differ by model? |
+| `gate_decisions_total` | `decision`: `update`, `noop`, `fail_open` | Is the gate saving consolidations? Is fail-open spiking? |
+| `scrub_decisions_total` | `decision`: `clean`, `cleaned`, `veto` | CID/PII pass health. |
+| `consolidation_results_total` | `result`: `rewritten`, `noop`, `malformed`, `llm_error`, `scrub_veto`, `unchanged_after_scrub` | Why a rewrite did not persist. |
+| `storage_duration_seconds` / `storage_total` | `op`: `folder_lookup`, `folder_create`, `download`, `upload`; `outcome`: `success`, `error`, `not_found`, `refused_empty` | Is the content store the bottleneck? |
+| `memory_length_tokens` / `memory_length_chars` | `phase`: `load`, `write` | How large are profiles in tokens and characters versus `max_tokens`? |
+| `condense_total` | `trigger`: `load`, `post_consolidation`, `condense`; `result`: `llm_ok`, `hard_cut`, `llm_failed_then_hard_cut` | How often the budget shrink path fires. |
+
+Token usage for billing still flows through `LanguageModelInvocationStats`, not these series.
+
 ## Integration
 
 Typical orchestration code loads memory before the agent loop and registers the postprocessor for the same turn.

unique_user_memory-2026.38.0.dev2/PKG-INFO → unique_user_memory-2026.40.0.dev0/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.3
-Name: unique-user-memory
-Version: 2026.38.0.dev2
-Summary: 
-Author: Fabian Schläpfer
-Author-email: Fabian Schläpfer <fabian@unique.ch>
-License: Proprietary
-Requires-Dist: jinja2>=3.1.6
-Requires-Dist: pydantic>=2.8.2
-Requires-Dist: unique-sdk>=2026.38.0.dev4,<2026.38.0rc0
-Requires-Dist: unique-toolkit>=2026.38.0.dev14,<2026.38.0rc0
-Requires-Python: >=3.12, <4
-Description-Content-Type: text/markdown
-
 # Unique User Memory
 
 Persistent per-user memory for Unique AI agents.
@@ -144,6 +130,27 @@ config = UserMemoryConfig(
 | `max_tokens` | `2000` | Maximum profile size. Must be between 500 and 8000 tokens. |
 | `root_folder` | `user-memory` | Subfolder name under each user's home folder (`/home-<user_id>/<root_folder>`) that holds the memory profile; also read as a legacy fallback at `/<root_folder>/<user_id>`. |
 
+## Observability
+
+The package registers Prometheus metrics on the shared `unique_toolkit.monitoring` registry (namespace `unique_user_memory`). They appear on whatever host already scrapes `GET /metrics` (assistants-core). Labels are closed enums — no company or user ids. LLM series include the model name so latency can be split per deployed model.
+
+QA dashboard: [User Memory](https://qa-grafana.alpine-bowfin.ts.net/d/unique-user-memory) (`unique-user-memory`). The dashboard is provisioned by the [assistants-core Helm chart](https://github.com/Unique-AG/monorepo/tree/master/python/assistants/bundles/core/deploy/helm-chart/files/grafana/dashboards).
+
+| Metric | Labels | What it answers |
+| --- | --- | --- |
+| `load_duration_seconds` / `load_total` | `outcome`: `success`, `empty`, `folder_failed`, `skipped_no_ids` | Is load slow? How often do we run without memory? |
+| `postprocessor_duration_seconds` / `postprocessor_total` | `outcome`: `updated`, `noop`, `upload_failed`, `skipped_no_ids`, `error` | Did this turn persist a new profile? |
+| `errors_total` | `stage`, `error_type` | Infra failures by stage (`folder_lookup`, `folder_create`, `download`, `upload`, `gate`, `consolidation`, `scrub`, `condense`, `postprocessor`). |
+| `llm_duration_seconds` / `llm_errors_total` | `purpose`: `gate`, `consolidation`, `scrub`, `condense`; `model`: the configured model name | Which LLM call is the latency or error hog, and how does that differ by model? |
+| `gate_decisions_total` | `decision`: `update`, `noop`, `fail_open` | Is the gate saving consolidations? Is fail-open spiking? |
+| `scrub_decisions_total` | `decision`: `clean`, `cleaned`, `veto` | CID/PII pass health. |
+| `consolidation_results_total` | `result`: `rewritten`, `noop`, `malformed`, `llm_error`, `scrub_veto`, `unchanged_after_scrub` | Why a rewrite did not persist. |
+| `storage_duration_seconds` / `storage_total` | `op`: `folder_lookup`, `folder_create`, `download`, `upload`; `outcome`: `success`, `error`, `not_found`, `refused_empty` | Is the content store the bottleneck? |
+| `memory_length_tokens` / `memory_length_chars` | `phase`: `load`, `write` | How large are profiles in tokens and characters versus `max_tokens`? |
+| `condense_total` | `trigger`: `load`, `post_consolidation`, `condense`; `result`: `llm_ok`, `hard_cut`, `llm_failed_then_hard_cut` | How often the budget shrink path fires. |
+
+Token usage for billing still flows through `LanguageModelInvocationStats`, not these series.
+
 ## Integration
 
 Typical orchestration code loads memory before the agent loop and registers the postprocessor for the same turn.

{unique_user_memory-2026.38.0.dev2 → unique_user_memory-2026.40.0.dev0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_user_memory"
-version = "2026.38.0.dev2"
+version = "2026.40.0.dev0"
 description = ""
 authors = [
     { name = "Fabian Schläpfer", email = "fabian@unique.ch" },
@@ -11,8 +11,8 @@ requires-python = ">=3.12,<4"
 dependencies = [
     "jinja2>=3.1.6",
     "pydantic>=2.8.2",
-    "unique-sdk>=2026.38.0.dev4,<2026.38.0rc0",
-    "unique-toolkit>=2026.38.0.dev14,<2026.38.0rc0",
+    "unique-sdk>=2026.40.0.dev0,<2026.40.0rc0",
+    "unique-toolkit[monitoring]>=2026.40.0.dev0,<2026.40.0rc0",
 ]
 
 [dependency-groups]

unique_user_memory-2026.40.0.dev0/unique_user_memory/metrics.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Protocol
+
+from unique_toolkit.monitoring import MetricNamespace
+
+
+class _ObservesSeconds(Protocol):
+    def observe(self, amount: float) -> None: ...
+
+
+m = MetricNamespace("unique_user_memory")
+
+_DURATION_BUCKETS = (0.1, 0.25, 0.5, 1.0, 2.0, 5.0, 10.0, 20.0, 30.0, 60.0)
+_TOKEN_BUCKETS = (
+    0.0,
+    100.0,
+    250.0,
+    500.0,
+    1000.0,
+    1500.0,
+    2000.0,
+    3000.0,
+    5000.0,
+    8000.0,
+)
+_CHAR_BUCKETS = (
+    0.0,
+    200.0,
+    500.0,
+    1000.0,
+    2000.0,
+    4000.0,
+    8000.0,
+    16000.0,
+    32000.0,
+)
+
+# End-to-end
+load_duration = m.histogram(
+    "load_duration_seconds",
+    "load_user_memory() duration",
+    [],
+    buckets=_DURATION_BUCKETS,
+)
+load_total = m.counter(
+    "load_total",
+    "Memory load attempts by outcome",
+    ["outcome"],
+)
+
+postprocessor_duration = m.histogram(
+    "postprocessor_duration_seconds",
+    "UserMemoryPostprocessor.run() duration",
+    [],
+    buckets=_DURATION_BUCKETS,
+)
+postprocessor_total = m.counter(
+    "postprocessor_total",
+    "Postprocessor runs by outcome",
+    ["outcome"],
+)
+
+errors = m.counter(
+    "errors_total",
+    "User memory infrastructure failures",
+    ["stage", "error_type"],
+)
+
+# LLM
+llm_duration = m.histogram(
+    "llm_duration_seconds",
+    "User memory LLM call duration",
+    ["purpose", "model"],
+    buckets=_DURATION_BUCKETS,
+)
+llm_errors = m.counter(
+    "llm_errors_total",
+    "User memory LLM call failures",
+    ["purpose", "model", "error_type"],
+)
+
+# Decisions
+gate_decisions = m.counter(
+    "gate_decisions_total",
+    "Consolidation gate decisions",
+    ["decision"],
+)
+scrub_decisions = m.counter(
+    "scrub_decisions_total",
+    "CID/PII scrub decisions",
+    ["decision"],
+)
+consolidation_results = m.counter(
+    "consolidation_results_total",
+    "Full-profile rewrite results",
+    ["result"],
+)
+
+# Storage
+storage_duration = m.histogram(
+    "storage_duration_seconds",
+    "Folder and content store latency",
+    ["op"],
+    buckets=_DURATION_BUCKETS,
+)
+storage_total = m.counter(
+    "storage_total",
+    "Folder and content store calls",
+    ["op", "outcome"],
+)
+
+# Size / budget
+memory_length_tokens = m.histogram(
+    "memory_length_tokens",
+    "Memory profile size in tokens",
+    ["phase"],
+    buckets=_TOKEN_BUCKETS,
+)
+memory_length_chars = m.histogram(
+    "memory_length_chars",
+    "Memory profile size in characters",
+    ["phase"],
+    buckets=_CHAR_BUCKETS,
+)
+condense_total = m.counter(
+    "condense_total",
+    "Over-budget condensation attempts",
+    ["trigger", "result"],
+)
+
+
+def record_error(stage: str, exc: BaseException) -> None:
+    errors.labels(stage=stage, error_type=type(exc).__name__).inc()
+
+
+def record_load(outcome: str) -> None:
+    load_total.labels(outcome=outcome).inc()
+
+
+def record_postprocessor(outcome: str) -> None:
+    postprocessor_total.labels(outcome=outcome).inc()
+
+
+def record_gate(decision: str) -> None:
+    gate_decisions.labels(decision=decision).inc()
+
+
+def record_scrub(decision: str) -> None:
+    scrub_decisions.labels(decision=decision).inc()
+
+
+def record_consolidation(result: str) -> None:
+    consolidation_results.labels(result=result).inc()
+
+
+def record_storage(op: str, outcome: str) -> None:
+    storage_total.labels(op=op, outcome=outcome).inc()
+
+
+def record_condense(trigger: str, result: str) -> None:
+    condense_total.labels(trigger=trigger, result=result).inc()
+
+
+def model_label(model_name: object) -> str:
+    """Stable Prometheus label for a language-model name (enum or string)."""
+    value = getattr(model_name, "value", model_name)
+    return str(value)
+
+
+def observe_memory_length(*, phase: str, content: str, tokens: float) -> None:
+    memory_length_tokens.labels(phase=phase).observe(tokens)
+    memory_length_chars.labels(phase=phase).observe(len(content))
+
+
+def condense_trigger(invocation_source: str) -> str:
+    if invocation_source == "user_memory_load_condense":
+        return "load"
+    if invocation_source == "user_memory_post_consolidation_condense":
+        return "post_consolidation"
+    return "condense"
+
+
+@contextmanager
+def observe_unlabeled(histogram: _ObservesSeconds) -> Iterator[None]:
+    """Time a block on a histogram that has no labels.
+
+    ``metric_scope`` always calls ``labels()``, which prometheus_client
+    rejects when the instrument was declared with an empty label set.
+    """
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        histogram.observe(time.perf_counter() - start)
+
+
+__all__ = [
+    "condense_total",
+    "condense_trigger",
+    "consolidation_results",
+    "errors",
+    "gate_decisions",
+    "llm_duration",
+    "llm_errors",
+    "load_duration",
+    "load_total",
+    "memory_length_chars",
+    "memory_length_tokens",
+    "model_label",
+    "observe_memory_length",
+    "observe_unlabeled",
+    "postprocessor_duration",
+    "postprocessor_total",
+    "record_condense",
+    "record_consolidation",
+    "record_error",
+    "record_gate",
+    "record_load",
+    "record_postprocessor",
+    "record_scrub",
+    "record_storage",
+    "scrub_decisions",
+    "storage_duration",
+    "storage_total",
+]