etchmem 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: etchmem
-Version: 0.3.0
-Summary: Python SDK for etchmem-server 0.0.4 — the Knowledge Consolidation Engine for AI agents
+Version: 0.4.0
+Summary: Python SDK for etchmem-server 0.0.10 — the Knowledge Consolidation Engine for AI agents
 Author: Andrey Olishchuk
 License: MIT
 Project-URL: Repository, https://github.com/vossmoos/etchmem-sdk-python
@@ -30,7 +30,9 @@ Dynamic: license-file
 
 **Python SDK for [etchmem-server](https://etchmem.io) — the Knowledge Consolidation Engine for AI agents.**
 
-Compatible with **etchmem-server 0.0.4**.
+Compatible with **etchmem-server 0.0.10** (`aolishchuk/etchmem:0.0.10`). Fields added
+after 0.0.4 (`details`, `evidence`, `event_at`, `values`, …) simply stay empty against
+older servers.
 
 Your agents' daily activity is full of hard-won facts — deals signed, decisions made, preferences learned. etchmem-server turns that stream of raw signals into a clean, typed, versioned knowledge base: one consolidated belief per fact, with confidence, provenance, conflict status, and full version history — queryable at any point in time.
 
@@ -65,7 +67,7 @@ for hit in mem.recall("what did Acme sign?", top_k=5):
     print(f"[{hit.origin}] {hit.content}  (confidence={hit.confidence})")
 ```
 
-### Three ways to ask
+### Four ways to ask
 
 Which one you want depends on what you already know. Reaching for the wrong one
 is a quiet source of wrong answers.
@@ -73,6 +75,7 @@ is a quiet source of wrong answers.
 | You know | Method | Returns |
 |---|---|---|
 | the subject | `know(ref)` | every belief about it — exhaustive, ordered by property |
+| the kind of belief (scope, property, subject type) | `etches(...)` | every matching belief across subjects — exhaustive, paged |
 | only words | `recall(query)` | beliefs ranked by wording, `top_k` |
 | words, and want what they connect to | `associate(query)` | the above **plus** each subject's full facts **plus** connected nodes |
 
@@ -83,6 +86,12 @@ for e in facts.settled(min_confidence=0.6):
     print(e.property, "=", e.current_value)
 print(facts.contested, "open questions")
 
+# etches — you know the kind of belief: every QA rule, across all subjects
+for e in mem.iter_etches(scope="content-qa", property="qa_rejection",
+                         min_confidence=0.8):
+    for d in e.details:                  # label + the author's full wording
+        print(e.entity_name, "·", d.value, "—", d.detail)
+
 # recall — you only have words. entity_id chains straight into know()
 for hit in mem.recall("bathroom leaks", top_k=5):
     detail = mem.know(hit.entity_id)
@@ -124,10 +133,13 @@ The SDK mirrors the REST endpoints one-to-one:
 | `remember(data, *, source, scope, extract_mode="deferred", metadata=None, occurred_at=None)` | `POST /remember` | `RememberResult` |
 | `recall(query, *, scope=None, source=None, top_k=5, include_signals=True, as_of=None, as_of_basis="ingest")` | `POST /recall` | `RecallResponse` (iterable of `RecallResult`) |
 | `know(ref, *, as_of=None, entity_type=None, as_of_basis="ingest")` | `GET /entity/{ref}/etches` | `Knowledge` (iterable of `Etch`) |
-| `associate(query, *, scope=None, top_k=5, hops=1, as_of=None, min_score=0.15)` | `POST /associate` | `Association` |
+| `associate(query, *, scope=None, top_k=5, hops=1, as_of=None, min_score=0.15, as_of_basis="ingest")` | `POST /associate` | `Association` |
+| `etches(*, scope=None, property=None, entity_type=None, status=None, min_confidence=None, limit=500, offset=0)` | `GET /etches` | `EtchList` (one page of `Etch`; `.total`, `.has_more`) |
+| `iter_etches(*, page_size=500, **filters)` | `GET /etches` (all pages) | iterator of `Etch` |
 | `sleep()` | `POST /sleep` | `SleepResult` |
 | `export()` | `POST /export` | `ExportResult` (list of `Etch`) |
 | `history(etch_id)` | `GET /etch/{id}/history` | `History` (iterable of `EtchVersion`) |
+| `dossier(etch_id)` | `GET /etch/{id}/dossier` | `Dossier` (etch + versions + claims + raw signals) |
 | `stats()` | `GET /stats` | `Stats` |
 | `health()` | `GET /health` | `Health` |
 
@@ -203,6 +215,41 @@ for v in mem.history(etch_id):
     print("  fact true from", v.event_at, "— we learned it", v.created_at)
 ```
 
+### retracted values
+
+From server 0.0.10 a withdrawn fact ("we no longer need CSV export") is kept, not
+deleted. `current_value` lists only what is still in force; `values` lists every value
+ever asserted, heaviest first, with `active`, `weight`, `last_asserted_at` and
+`retracted_at`:
+
+```python
+for e in mem.know("Acme"):
+    print(e.property, "=", e.current_value)
+    for v in e.retracted:                       # no longer valid, but once was
+        print("   withdrawn:", v.value, "at", v.retracted_at)
+```
+
+### evidence and dossier
+
+`confidence` is built from who said it (source trust declared in the server's
+`ext/*.yaml`) and how many independent sources agree. Every etch and recall hit
+carries the `evidence` behind the number, so you can apply your own rule:
+
+```python
+for hit in mem.recall(paragraph, scope="content-qa", include_signals=False):
+    if hit.evidence and hit.evidence.max_trust >= 0.8:
+        print(hit.value, [s.source for s in hit.evidence.sources])
+```
+
+`dossier(etch_id)` answers "why does the agent believe that?" in one call: the
+etch, its versions, the claims that formed it (with corroboration counts) and the
+raw signals behind them. Raw signals are withheld (`signals_omitted=True`) when
+the server runs with claims anonymization.
+
+`sleep()` also reports `subject_retries`, `relations_resolved` and the
+`entities` resolution counters; `stats().sources_without_trust` lists deposit
+sources nobody declared a trust for.
+
 ---
 
 ## Configuration

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

@@ -2,7 +2,9 @@
 
 **Python SDK for [etchmem-server](https://etchmem.io) — the Knowledge Consolidation Engine for AI agents.**
 
-Compatible with **etchmem-server 0.0.4**.
+Compatible with **etchmem-server 0.0.10** (`aolishchuk/etchmem:0.0.10`). Fields added
+after 0.0.4 (`details`, `evidence`, `event_at`, `values`, …) simply stay empty against
+older servers.
 
 Your agents' daily activity is full of hard-won facts — deals signed, decisions made, preferences learned. etchmem-server turns that stream of raw signals into a clean, typed, versioned knowledge base: one consolidated belief per fact, with confidence, provenance, conflict status, and full version history — queryable at any point in time.
 
@@ -37,7 +39,7 @@ for hit in mem.recall("what did Acme sign?", top_k=5):
     print(f"[{hit.origin}] {hit.content}  (confidence={hit.confidence})")
 ```
 
-### Three ways to ask
+### Four ways to ask
 
 Which one you want depends on what you already know. Reaching for the wrong one
 is a quiet source of wrong answers.
@@ -45,6 +47,7 @@ is a quiet source of wrong answers.
 | You know | Method | Returns |
 |---|---|---|
 | the subject | `know(ref)` | every belief about it — exhaustive, ordered by property |
+| the kind of belief (scope, property, subject type) | `etches(...)` | every matching belief across subjects — exhaustive, paged |
 | only words | `recall(query)` | beliefs ranked by wording, `top_k` |
 | words, and want what they connect to | `associate(query)` | the above **plus** each subject's full facts **plus** connected nodes |
 
@@ -55,6 +58,12 @@ for e in facts.settled(min_confidence=0.6):
     print(e.property, "=", e.current_value)
 print(facts.contested, "open questions")
 
+# etches — you know the kind of belief: every QA rule, across all subjects
+for e in mem.iter_etches(scope="content-qa", property="qa_rejection",
+                         min_confidence=0.8):
+    for d in e.details:                  # label + the author's full wording
+        print(e.entity_name, "·", d.value, "—", d.detail)
+
 # recall — you only have words. entity_id chains straight into know()
 for hit in mem.recall("bathroom leaks", top_k=5):
     detail = mem.know(hit.entity_id)
@@ -96,10 +105,13 @@ The SDK mirrors the REST endpoints one-to-one:
 | `remember(data, *, source, scope, extract_mode="deferred", metadata=None, occurred_at=None)` | `POST /remember` | `RememberResult` |
 | `recall(query, *, scope=None, source=None, top_k=5, include_signals=True, as_of=None, as_of_basis="ingest")` | `POST /recall` | `RecallResponse` (iterable of `RecallResult`) |
 | `know(ref, *, as_of=None, entity_type=None, as_of_basis="ingest")` | `GET /entity/{ref}/etches` | `Knowledge` (iterable of `Etch`) |
-| `associate(query, *, scope=None, top_k=5, hops=1, as_of=None, min_score=0.15)` | `POST /associate` | `Association` |
+| `associate(query, *, scope=None, top_k=5, hops=1, as_of=None, min_score=0.15, as_of_basis="ingest")` | `POST /associate` | `Association` |
+| `etches(*, scope=None, property=None, entity_type=None, status=None, min_confidence=None, limit=500, offset=0)` | `GET /etches` | `EtchList` (one page of `Etch`; `.total`, `.has_more`) |
+| `iter_etches(*, page_size=500, **filters)` | `GET /etches` (all pages) | iterator of `Etch` |
 | `sleep()` | `POST /sleep` | `SleepResult` |
 | `export()` | `POST /export` | `ExportResult` (list of `Etch`) |
 | `history(etch_id)` | `GET /etch/{id}/history` | `History` (iterable of `EtchVersion`) |
+| `dossier(etch_id)` | `GET /etch/{id}/dossier` | `Dossier` (etch + versions + claims + raw signals) |
 | `stats()` | `GET /stats` | `Stats` |
 | `health()` | `GET /health` | `Health` |
 
@@ -175,6 +187,41 @@ for v in mem.history(etch_id):
     print("  fact true from", v.event_at, "— we learned it", v.created_at)
 ```
 
+### retracted values
+
+From server 0.0.10 a withdrawn fact ("we no longer need CSV export") is kept, not
+deleted. `current_value` lists only what is still in force; `values` lists every value
+ever asserted, heaviest first, with `active`, `weight`, `last_asserted_at` and
+`retracted_at`:
+
+```python
+for e in mem.know("Acme"):
+    print(e.property, "=", e.current_value)
+    for v in e.retracted:                       # no longer valid, but once was
+        print("   withdrawn:", v.value, "at", v.retracted_at)
+```
+
+### evidence and dossier
+
+`confidence` is built from who said it (source trust declared in the server's
+`ext/*.yaml`) and how many independent sources agree. Every etch and recall hit
+carries the `evidence` behind the number, so you can apply your own rule:
+
+```python
+for hit in mem.recall(paragraph, scope="content-qa", include_signals=False):
+    if hit.evidence and hit.evidence.max_trust >= 0.8:
+        print(hit.value, [s.source for s in hit.evidence.sources])
+```
+
+`dossier(etch_id)` answers "why does the agent believe that?" in one call: the
+etch, its versions, the claims that formed it (with corroboration counts) and the
+raw signals behind them. Raw signals are withheld (`signals_omitted=True`) when
+the server runs with claims anonymization.
+
+`sleep()` also reports `subject_retries`, `relations_resolved` and the
+`entities` resolution counters; `stats().sources_without_trust` lists deposit
+sources nobody declared a trust for.
+
 ---
 
 ## Configuration

{etchmem-0.3.0 → etchmem-0.4.0}/etchmem/__init__.py

@@ -24,8 +24,10 @@ from etchmem.errors import (
     NotFoundError, ServerError,
 )
 from etchmem.models import (
-    Association, EntityInfo, Etch, EtchVersion, ExportResult, Health, History,
-    Knowledge, RecallResponse, RecallResult, RememberResult, SleepResult, Stats,
+    Association, Claim, DetailItem, Dossier, EntityInfo, Etch, EtchList,
+    EtchVersion, Evidence, ExportResult, Health, History, Knowledge,
+    RecallResponse, RecallResult, RememberResult, Signal, SleepResult,
+    SourceEvidence, Stats, ValueWeight,
 )
 
 __all__ = [
@@ -41,8 +43,16 @@ __all__ = [
     "SleepResult",
     "ExportResult",
     "Etch",
+    "EtchList",
     "EtchVersion",
     "History",
+    "Dossier",
+    "Claim",
+    "Signal",
+    "DetailItem",
+    "Evidence",
+    "SourceEvidence",
+    "ValueWeight",
     "Stats",
     "Health",
     # errors
@@ -54,4 +64,4 @@ __all__ = [
     "ServerError",
 ]
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{etchmem-0.3.0 → etchmem-0.4.0}/etchmem/async_client.py

@@ -2,15 +2,18 @@
 from __future__ import annotations
 
 import os
+from collections.abc import AsyncIterator, Sequence
 from typing import Any
 
 import httpx
 
-from etchmem.client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+from etchmem.client import (
+    DEFAULT_BASE_URL, DEFAULT_TIMEOUT, _etch_filters, _ref_path,
+)
 from etchmem.errors import ConnectionError, error_for_status
 from etchmem.models import (
-    ExportResult, Health, History, RecallResponse, RememberResult,
-    SleepResult, Stats,
+    Association, Dossier, Etch, EtchList, ExportResult, Health, History,
+    Knowledge, RecallResponse, RememberResult, SleepResult, Stats,
 )
 
 
@@ -115,9 +118,6 @@ class AsyncEtchMem:
             "as_of_basis": as_of_basis})
         return RecallResponse.from_dict(payload)
 
-
-
-
     async def associate(
         self,
         query: str,
@@ -172,9 +172,43 @@ class AsyncEtchMem:
         if as_of_basis != "ingest":
             params["as_of_basis"] = as_of_basis
         payload = await self._request(
-            "GET", f"/entity/{ref}/etches", params=params or None)
+            "GET", f"/entity/{_ref_path(ref)}/etches", params=params or None)
         return Knowledge.from_dict(payload)
 
+    async def etches(
+        self,
+        *,
+        scope: str | None = None,
+        property: str | Sequence[str] | None = None,
+        entity_type: str | Sequence[str] | None = None,
+        status: str | None = None,
+        min_confidence: float | None = None,
+        limit: int = 500,
+        offset: int = 0,
+    ) -> EtchList:
+        """EVERY belief matching plain filters — exhaustive, not ranked.
+
+        Use when you know the *kind* of belief rather than the subject or the
+        words: "all qa_rejection rules in scope content-qa", "every contested
+        lifecycle_status". ``property`` and ``entity_type`` take one value or a
+        list. Returns one page (newest first); ``total`` counts every match, so
+        page with ``offset`` or use :meth:`iter_etches`.
+        """
+        return EtchList.from_dict(await self._request(
+            "GET", "/etches", params=_etch_filters(
+                scope, property, entity_type, status, min_confidence, limit, offset)))
+
+    async def iter_etches(self, *, page_size: int = 500, **filters: Any) -> AsyncIterator[Etch]:
+        """Every belief matching the filters of :meth:`etches`, across all pages."""
+        offset = 0
+        while True:
+            page = await self.etches(limit=page_size, offset=offset, **filters)
+            for etch in page.etches:
+                yield etch
+            if not page.has_more or not page.etches:
+                return
+            offset += page.count
+
     async def sleep(self) -> SleepResult:
         """Run one consolidation tick now (batch → extract → fold)."""
         return SleepResult.from_dict(await self._request("POST", "/sleep"))
@@ -188,6 +222,15 @@ class AsyncEtchMem:
         return History.from_dict(
             await self._request("GET", f"/etch/{etch_id}/history"))
 
+    async def dossier(self, etch_id: str) -> Dossier:
+        """Full provenance of one belief: etch, versions, claims, raw signals.
+
+        The answer to "why does the agent believe that?". Raw signals are
+        withheld (``signals_omitted=True``) when the server anonymizes claims.
+        """
+        return Dossier.from_dict(
+            await self._request("GET", f"/etch/{etch_id}/dossier"))
+
     async def stats(self) -> Stats:
         """Queue depths and store counts."""
         return Stats.from_dict(await self._request("GET", "/stats"))

{etchmem-0.3.0 → etchmem-0.4.0}/etchmem/client.py

@@ -2,20 +2,43 @@
 from __future__ import annotations
 
 import os
+from collections.abc import Iterator, Sequence
 from typing import Any
+from urllib.parse import quote
 
 import httpx
 
 from etchmem.errors import ConnectionError, error_for_status
 from etchmem.models import (
-    ExportResult, Health, History, RecallResponse, RememberResult,
-    SleepResult, Stats,
+    Association, Dossier, Etch, EtchList, ExportResult, Health, History,
+    Knowledge, RecallResponse, RememberResult, SleepResult, Stats,
 )
 
 DEFAULT_BASE_URL = "http://localhost:8000"
 DEFAULT_TIMEOUT = 30.0
 
 
+def _etch_filters(scope: str | None, property: str | Sequence[str] | None,
+                  entity_type: str | Sequence[str] | None, status: str | None,
+                  min_confidence: float | None, limit: int,
+                  offset: int) -> dict[str, Any]:
+    """Query params for GET /etches; list filters become repeated params."""
+    params: dict[str, Any] = {"limit": limit, "offset": offset}
+    for key, value in (("scope", scope), ("status", status),
+                       ("min_confidence", min_confidence)):
+        if value is not None:
+            params[key] = value
+    for key, value in (("property", property), ("entity_type", entity_type)):
+        if value:
+            params[key] = [value] if isinstance(value, str) else list(value)
+    return params
+
+
+def _ref_path(ref: str) -> str:
+    """Percent-encode an entity ref for the URL path ("MSM 0808", "R&D #4")."""
+    return quote(ref, safe="")
+
+
 class EtchMem:
     """Synchronous etchmem client.
 
@@ -139,9 +162,6 @@ class EtchMem:
             "as_of_basis": as_of_basis})
         return RecallResponse.from_dict(payload)
 
-
-
-
     def associate(
         self,
         query: str,
@@ -196,9 +216,42 @@ class EtchMem:
         if as_of_basis != "ingest":
             params["as_of_basis"] = as_of_basis
         payload = self._request(
-            "GET", f"/entity/{ref}/etches", params=params or None)
+            "GET", f"/entity/{_ref_path(ref)}/etches", params=params or None)
         return Knowledge.from_dict(payload)
 
+    def etches(
+        self,
+        *,
+        scope: str | None = None,
+        property: str | Sequence[str] | None = None,
+        entity_type: str | Sequence[str] | None = None,
+        status: str | None = None,
+        min_confidence: float | None = None,
+        limit: int = 500,
+        offset: int = 0,
+    ) -> EtchList:
+        """EVERY belief matching plain filters — exhaustive, not ranked.
+
+        Use when you know the *kind* of belief rather than the subject or the
+        words: "all qa_rejection rules in scope content-qa", "every contested
+        lifecycle_status". ``property`` and ``entity_type`` take one value or a
+        list. Returns one page (newest first); ``total`` counts every match, so
+        page with ``offset`` or use :meth:`iter_etches`.
+        """
+        return EtchList.from_dict(self._request(
+            "GET", "/etches", params=_etch_filters(
+                scope, property, entity_type, status, min_confidence, limit, offset)))
+
+    def iter_etches(self, *, page_size: int = 500, **filters: Any) -> Iterator[Etch]:
+        """Every belief matching the filters of :meth:`etches`, across all pages."""
+        offset = 0
+        while True:
+            page = self.etches(limit=page_size, offset=offset, **filters)
+            yield from page.etches
+            if not page.has_more or not page.etches:
+                return
+            offset += page.count
+
     def sleep(self) -> SleepResult:
         """Run one consolidation tick now (batch → extract → fold)."""
         return SleepResult.from_dict(self._request("POST", "/sleep"))
@@ -212,6 +265,15 @@ class EtchMem:
         return History.from_dict(
             self._request("GET", f"/etch/{etch_id}/history"))
 
+    def dossier(self, etch_id: str) -> Dossier:
+        """Full provenance of one belief: etch, versions, claims, raw signals.
+
+        The answer to "why does the agent believe that?". Raw signals are
+        withheld (``signals_omitted=True``) when the server anonymizes claims.
+        """
+        return Dossier.from_dict(
+            self._request("GET", f"/etch/{etch_id}/dossier"))
+
     def stats(self) -> Stats:
         """Queue depths and store counts."""
         return Stats.from_dict(self._request("GET", "/stats"))