pdm-memory 0.2.0__tar.gz → 0.2.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/PKG-INFO +15 -3
  2. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/README.md +14 -2
  3. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/__init__.py +5 -5
  4. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/auth/jwt_handler.py +11 -13
  5. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/core/alignment.py +22 -10
  6. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/core/math.py +8 -10
  7. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/core/retrieval.py +230 -54
  8. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/core/signature.py +35 -24
  9. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/ingest/__init__.py +2 -2
  10. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/ingest/auto_signature.py +7 -7
  11. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/ingest/batch.py +9 -8
  12. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/ingest/ingester.py +13 -13
  13. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/integrations/__init__.py +13 -13
  14. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/integrations/anthropic_adapter.py +5 -5
  15. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/integrations/context_manager.py +6 -7
  16. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/integrations/gemini_adapter.py +5 -5
  17. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/integrations/groq_adapter.py +5 -5
  18. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/integrations/ollama_adapter.py +5 -5
  19. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/integrations/openai_adapter.py +5 -5
  20. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/io/json_transfer.py +7 -5
  21. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/memory.py +298 -74
  22. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/models.py +7 -7
  23. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/storage/base.py +10 -9
  24. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/storage/cloud_driver.py +19 -13
  25. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/storage/factory.py +12 -2
  26. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/storage/postgres_driver.py +13 -11
  27. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/storage/schema.py +31 -11
  28. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/storage/sqlite_driver.py +21 -18
  29. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/sync.py +2 -0
  30. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/tools/bench.py +10 -11
  31. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/tools/cli.py +61 -1
  32. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/tools/explorer_actions.py +3 -3
  33. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/tools/server.py +4 -4
  34. pdm_memory-0.2.3/pdm_memory/types.py +37 -0
  35. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory.egg-info/PKG-INFO +15 -3
  36. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory.egg-info/SOURCES.txt +2 -0
  37. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pyproject.toml +4 -1
  38. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_alignment.py +39 -7
  39. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_cli.py +88 -11
  40. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_gemini_adapter.py +1 -0
  41. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_groq_adapter.py +1 -0
  42. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_jwt_auth.py +21 -2
  43. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_math.py +7 -6
  44. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_memory.py +211 -0
  45. pdm_memory-0.2.3/tests/test_memory_hooks.py +110 -0
  46. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_ollama_adapter.py +1 -0
  47. pdm_memory-0.2.3/tests/test_retrieval_diversity.py +198 -0
  48. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_sqlite_driver.py +66 -5
  49. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_storage_factory.py +36 -2
  50. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_tier2.py +12 -8
  51. pdm_memory-0.2.0/pdm_memory/types.py +0 -19
  52. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/LICENSE +0 -0
  53. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/auth/__init__.py +0 -0
  54. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/bench.py +0 -0
  55. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/core/__init__.py +0 -0
  56. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/io/__init__.py +0 -0
  57. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/storage/__init__.py +0 -0
  58. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/storage/errors.py +0 -0
  59. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/tools/__init__.py +0 -0
  60. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory/tools/static/index.html +0 -0
  61. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory.egg-info/dependency_links.txt +0 -0
  62. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory.egg-info/entry_points.txt +0 -0
  63. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory.egg-info/requires.txt +0 -0
  64. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/pdm_memory.egg-info/top_level.txt +0 -0
  65. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/setup.cfg +0 -0
  66. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_bench.py +0 -0
  67. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_cloud_driver.py +0 -0
  68. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_explorer_console.py +0 -0
  69. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_explorer_ui.py +0 -0
  70. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_pdm_concurrency.py +0 -0
  71. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_pdm_physics.py +0 -0
  72. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_tier3.py +1 -1
  73. {pdm_memory-0.2.0 → pdm_memory-0.2.3}/tests/test_torsion.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pdm-memory
3
- Version: 0.2.0
3
+ Version: 0.2.3
4
4
  Summary: Pressure-Driven Memory (PDM) — persistent, resonance-based memory for AI apps.
5
5
  Author: Westfield Innovations LLC
6
6
  License: Elastic License 2.0 (ELv2)
@@ -189,7 +189,7 @@ Your LLM forgets everything between conversations. The standard fix — stuff a
189
189
 
190
190
  📖 **Documentation:** [azus.ai/support](https://azus.ai/support)
191
191
 
192
- **Benchmarks vs standard RAG:** [link] · Run yourself: `python -m pdm_memory.bench`
192
+ **Benchmarks vs standard RAG:** [azus.ai/pdm/benchmarks](https://azus.ai/pdm/benchmarks)
193
193
 
194
194
  ---
195
195
 
@@ -313,7 +313,7 @@ from pdm_memory.auth import JWTAuth
313
313
  auth = JWTAuth(
314
314
  token="eyJ...",
315
315
  refresh_token="eyJ...",
316
- refresh_url="https://api.azus.ai/api/v1/accounts/auth/refresh/",
316
+ refresh_url="https://api.azus.ai/api/v1/accounts/token/refresh/",
317
317
  )
318
318
  ```
319
319
 
@@ -414,6 +414,18 @@ mem.ingest(
414
414
 
415
415
  ## 🛠️ Developer Tools
416
416
 
417
+ ### Examples (DX walkthrough)
418
+
419
+ ```bash
420
+ pip install .
421
+ python examples/hello_pdm.py # save / recall / explain
422
+ python examples/guarded_agent_logic.py # GAA: TORSION vs ALIGNED
423
+ python examples/handling_contradictions.py # detect + reconcile torsion
424
+ python examples/temporal_recall_demo.py # event_at + deadline (PDM-T)
425
+ ```
426
+
427
+ See [`examples/README.md`](examples/README.md).
428
+
417
429
  ### The explain Method
418
430
 
419
431
  ```python
@@ -16,7 +16,7 @@ Your LLM forgets everything between conversations. The standard fix — stuff a
16
16
 
17
17
  📖 **Documentation:** [azus.ai/support](https://azus.ai/support)
18
18
 
19
- **Benchmarks vs standard RAG:** [link] · Run yourself: `python -m pdm_memory.bench`
19
+ **Benchmarks vs standard RAG:** [azus.ai/pdm/benchmarks](https://azus.ai/pdm/benchmarks)
20
20
 
21
21
  ---
22
22
 
@@ -140,7 +140,7 @@ from pdm_memory.auth import JWTAuth
140
140
  auth = JWTAuth(
141
141
  token="eyJ...",
142
142
  refresh_token="eyJ...",
143
- refresh_url="https://api.azus.ai/api/v1/accounts/auth/refresh/",
143
+ refresh_url="https://api.azus.ai/api/v1/accounts/token/refresh/",
144
144
  )
145
145
  ```
146
146
 
@@ -241,6 +241,18 @@ mem.ingest(
241
241
 
242
242
  ## 🛠️ Developer Tools
243
243
 
244
+ ### Examples (DX walkthrough)
245
+
246
+ ```bash
247
+ pip install .
248
+ python examples/hello_pdm.py # save / recall / explain
249
+ python examples/guarded_agent_logic.py # GAA: TORSION vs ALIGNED
250
+ python examples/handling_contradictions.py # detect + reconcile torsion
251
+ python examples/temporal_recall_demo.py # event_at + deadline (PDM-T)
252
+ ```
253
+
254
+ See [`examples/README.md`](examples/README.md).
255
+
244
256
  ### The explain Method
245
257
 
246
258
  ```python
@@ -19,20 +19,20 @@ The public surface of the SDK:
19
19
  See README.md for full documentation.
20
20
  """
21
21
 
22
+ from pdm_memory.core.signature import DrawerInfo, MemoryHit
22
23
  from pdm_memory.memory import Memory
23
- from pdm_memory.core.signature import MemoryHit, DrawerInfo
24
24
  from pdm_memory.models import AlignmentReport, SurfaceReport, TorsionReport
25
25
  from pdm_memory.storage.factory import create_storage, register_storage
26
26
 
27
- __version__ = "0.2.0"
27
+ __version__ = "0.2.3"
28
28
  __all__ = [
29
+ "AlignmentReport",
30
+ "DrawerInfo",
29
31
  "Memory",
30
32
  "MemoryHit",
31
- "DrawerInfo",
32
- "AlignmentReport",
33
33
  "SurfaceReport",
34
34
  "TorsionReport",
35
+ "__version__",
35
36
  "create_storage",
36
37
  "register_storage",
37
- "__version__",
38
38
  ]
@@ -9,7 +9,7 @@ Manages Bearer token authentication for cloud storage requests.
9
9
  Optionally handles refresh-token flows automatically on 401.
10
10
 
11
11
  Usage:
12
- auth = JWTAuth(token="eyJ...", refresh_token="eyJ...", refresh_url="https://api.azus.ai/api/v1/accounts/auth/refresh/")
12
+ auth = JWTAuth(token="eyJ...", refresh_token="eyJ...", refresh_url="https://api.azus.ai/api/v1/accounts/token/refresh/")
13
13
  headers = auth.headers()
14
14
  """
15
15
 
@@ -17,7 +17,6 @@ from __future__ import annotations
17
17
 
18
18
  import logging
19
19
  import time
20
- from typing import Dict, Optional
21
20
 
22
21
  logger = logging.getLogger(__name__)
23
22
 
@@ -36,15 +35,15 @@ class JWTAuth:
36
35
  def __init__(
37
36
  self,
38
37
  token: str,
39
- refresh_token: Optional[str] = None,
40
- refresh_url: Optional[str] = None,
38
+ refresh_token: str | None = None,
39
+ refresh_url: str | None = None,
41
40
  expire_buffer: int = 60,
42
41
  ) -> None:
43
42
  self._token = token
44
43
  self._refresh_token = refresh_token
45
44
  self._refresh_url = refresh_url
46
45
  self._expire_buffer = expire_buffer
47
- self._expires_at: Optional[float] = self._decode_exp(token)
46
+ self._expires_at: float | None = self._decode_exp(token)
48
47
 
49
48
  # ------------------------------------------------------------------
50
49
  # Public API
@@ -54,7 +53,7 @@ class JWTAuth:
54
53
  def token(self) -> str:
55
54
  return self._token
56
55
 
57
- def headers(self) -> Dict[str, str]:
56
+ def headers(self) -> dict[str, str]:
58
57
  """Return Authorization headers for an HTTP request."""
59
58
  return {"Authorization": f"Bearer {self._token}"}
60
59
 
@@ -93,19 +92,18 @@ class JWTAuth:
93
92
 
94
93
  def ensure_fresh(self) -> None:
95
94
  """Refresh token if expired. Raises RuntimeError if refresh fails."""
96
- if self.is_expired():
97
- if not self.refresh():
98
- raise RuntimeError(
99
- "PDM cloud auth: access token is expired and could not be refreshed. "
100
- "Please provide a new token via Memory(token=...)."
101
- )
95
+ if self.is_expired() and not self.refresh():
96
+ raise RuntimeError(
97
+ "PDM cloud auth: access token is expired and could not be refreshed. "
98
+ "Please provide a new token via Memory(token=...)."
99
+ )
102
100
 
103
101
  # ------------------------------------------------------------------
104
102
  # Private
105
103
  # ------------------------------------------------------------------
106
104
 
107
105
  @staticmethod
108
- def _decode_exp(token: str) -> Optional[float]:
106
+ def _decode_exp(token: str) -> float | None:
109
107
  """Decode the 'exp' claim from a JWT without validating the signature."""
110
108
  try:
111
109
  import base64
@@ -13,8 +13,9 @@ suitable as a final gate before an agent ACT.
13
13
  from __future__ import annotations
14
14
 
15
15
  import re
16
+ from collections.abc import Sequence
16
17
  from dataclasses import dataclass
17
- from typing import List, Optional, Sequence, TYPE_CHECKING
18
+ from typing import TYPE_CHECKING
18
19
 
19
20
  from pdm_memory.core.math import calculate_intent_weight, infer_domain
20
21
  from pdm_memory.core.signature import SignatureRecord
@@ -158,9 +159,9 @@ def select_goal_anchors(
158
159
  *,
159
160
  min_pressure: float = DEFAULT_MIN_PRESSURE,
160
161
  k: int = DEFAULT_K_GOALS,
161
- ) -> List[SignatureRecord]:
162
+ ) -> list[SignatureRecord]:
162
163
  """High-pressure stewardship/foundational signatures ranked by IAW."""
163
- pool: List[tuple[float, SignatureRecord]] = []
164
+ pool: list[tuple[float, SignatureRecord]] = []
164
165
  for rec in records:
165
166
  if float(rec.p_magnitude or 0.0) < min_pressure:
166
167
  continue
@@ -232,7 +233,7 @@ def _forbidden_after_negation(goal_text: str) -> set[str]:
232
233
 
233
234
 
234
235
  def intent_goal_resonance(
235
- engine: "RetrievalEngine",
236
+ engine: RetrievalEngine,
236
237
  intent_text: str,
237
238
  goal: SignatureRecord,
238
239
  ) -> float:
@@ -332,7 +333,7 @@ def _stem(token: str) -> str:
332
333
 
333
334
 
334
335
  def verify_alignment(
335
- engine: "RetrievalEngine",
336
+ engine: RetrievalEngine,
336
337
  records: Sequence[SignatureRecord],
337
338
  intent_text: str,
338
339
  *,
@@ -345,6 +346,10 @@ def verify_alignment(
345
346
  Compare a proposed intent to high-IAW goal anchors.
346
347
 
347
348
  Fail-closed when no anchors exist (guarded agents must not ACT blind).
349
+
350
+ Resonance is self-weighted by ``(resonance × IAW)`` so unrelated
351
+ stewardship goals do not dilute a strongly matching intent. Peak
352
+ torsion is still taken across *all* anchors (fail-closed on danger).
348
353
  """
349
354
  text = (intent_text or "").strip()
350
355
  if not text:
@@ -365,7 +370,7 @@ def verify_alignment(
365
370
  anchor_count=0,
366
371
  )
367
372
 
368
- scored: List[_AnchorScore] = []
373
+ scored: list[_AnchorScore] = []
369
374
  for goal in anchors:
370
375
  iaw = compute_iaw(goal)
371
376
  resonance = intent_goal_resonance(engine, text, goal)
@@ -382,9 +387,16 @@ def verify_alignment(
382
387
  )
383
388
  )
384
389
 
385
- # IAW-weighted mean resonance; peak torsion drives status
390
+ # IAW-weighted resonance that resists dilution from unrelated anchors:
391
+ # weight each goal by (resonance × IAW) so low-resonance stewardship
392
+ # goals (e.g. audit) do not tank a deploy/validate intent.
393
+ # Torsion still uses the peak across ALL anchors — fail-closed on danger.
386
394
  iaw_sum = sum(s.iaw for s in scored) or 1.0
387
- resonance = sum(s.resonance * s.iaw for s in scored) / iaw_sum
395
+ soft_sum = sum(s.resonance * s.iaw for s in scored)
396
+ if soft_sum > 1e-9:
397
+ resonance = sum(s.resonance * s.resonance * s.iaw for s in scored) / soft_sum
398
+ else:
399
+ resonance = sum(s.resonance * s.iaw for s in scored) / iaw_sum
388
400
  peak = max(scored, key=lambda s: s.torsion)
389
401
  torsion = peak.torsion
390
402
 
@@ -456,7 +468,7 @@ def _explain_conflict(
456
468
  )
457
469
 
458
470
 
459
- def _tokenize(text: str) -> List[str]:
471
+ def _tokenize(text: str) -> list[str]:
460
472
  words = _WORD_RE.findall((text or "").lower())
461
473
  stop = {
462
474
  "the", "and", "for", "how", "what", "that", "this", "with",
@@ -466,7 +478,7 @@ def _tokenize(text: str) -> List[str]:
466
478
  return [w for w in words if w not in stop]
467
479
 
468
480
 
469
- def _snip(text: Optional[str], max_len: int = 80) -> str:
481
+ def _snip(text: str | None, max_len: int = 80) -> str:
470
482
  cleaned = " ".join((text or "").split())
471
483
  if not cleaned:
472
484
  return "empty"
@@ -24,14 +24,12 @@ from __future__ import annotations
24
24
 
25
25
  import math
26
26
  import warnings
27
- from typing import Dict, List, Optional
28
-
29
27
 
30
28
  # ---------------------------------------------------------------------------
31
29
  # Domain half-lives (ported from kernel.py DOMAIN_HALF_LIVES)
32
30
  # ---------------------------------------------------------------------------
33
31
 
34
- DOMAIN_HALF_LIVES: Dict[str, float] = {
32
+ DOMAIN_HALF_LIVES: dict[str, float] = {
35
33
  "market_signal": 1.0, # 1 day
36
34
  "pattern": 14.0, # 2 weeks
37
35
  "structural": 90.0, # 3 months
@@ -80,7 +78,7 @@ def calculate_effective_spike(
80
78
  return min(P_MAX, max(P_FLOOR, raw))
81
79
 
82
80
 
83
- def resolve_half_life(domain: Optional[str]) -> float:
81
+ def resolve_half_life(domain: str | None) -> float:
84
82
  """Map knowledge domain → half-life days (canonical decay clock)."""
85
83
  if not domain:
86
84
  return DEFAULT_HALF_LIFE
@@ -91,7 +89,7 @@ def calculate_decay_factor(
91
89
  days_since_retrieved: float,
92
90
  half_life: float = DEFAULT_HALF_LIFE,
93
91
  *,
94
- days_since_created: Optional[float] = None,
92
+ days_since_created: float | None = None,
95
93
  t_persistence: float = 0.0,
96
94
  ) -> float:
97
95
  """
@@ -132,8 +130,8 @@ def calculate_v(correct: int, total: int) -> float:
132
130
 
133
131
 
134
132
  def calculate_intent_weight(
135
- intent_tags: List[str],
136
- query: Optional[str] = None,
133
+ intent_tags: list[str],
134
+ query: str | None = None,
137
135
  ) -> float:
138
136
  """
139
137
  Intent match weight: 0.8 base + 0.2 boost proportional to tag-query overlap.
@@ -199,7 +197,7 @@ def calculate_half_life_pressure(
199
197
  t_persistence: float,
200
198
  phase_privilege: float = 1.0,
201
199
  *,
202
- days_since_created: Optional[float] = None,
200
+ days_since_created: float | None = None,
203
201
  ) -> tuple[float, float]:
204
202
  """
205
203
  Project stored pressure after canonical half-life decay.
@@ -341,7 +339,7 @@ def calculate_temporal_geometry(
341
339
  # ---------------------------------------------------------------------------
342
340
 
343
341
 
344
- def infer_domain(tags: List[str]) -> str:
342
+ def infer_domain(tags: list[str]) -> str:
345
343
  """Infer memory domain from intent tags."""
346
344
  if not tags:
347
345
  return "insight"
@@ -361,7 +359,7 @@ def infer_domain(tags: List[str]) -> str:
361
359
  return "insight"
362
360
 
363
361
 
364
- def infer_regime(tags: List[str]) -> str:
362
+ def infer_regime(tags: list[str]) -> str:
365
363
  """Infer question regime from intent tags."""
366
364
  tag_str = " ".join(tags).lower()
367
365
  if any(k in tag_str for k in ["trade", "stock", "market", "price"]):