From a1e84106bfd48755ab59d36fb006df781ec7cac2 Mon Sep 17 00:00:00 2001 From: Pierre Brunelle Date: Thu, 15 Oct 2026 21:00:52 -0700 Subject: [PATCH] Document migration from the published Pixelmemory 0.1.0 API --- .github/workflows/release.yml | 2 +- README.md | 46 +++++++++++++++++++++++++++++++---- RELEASING.md | 3 ++- 3 files changed, 44 insertions(+), 7 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index cb823c0..21cb472 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -9,7 +9,7 @@ name: Release # rotate, or paste into a shell. The previous scripts/release.sh read one out of # ~/.pixeltable/config.toml. # -# One-time setup on PyPI (Manage project -> Publishing -> Add a pending publisher): +# One-time setup on PyPI (Manage project -> Publishing -> add a GitHub publisher): # owner: pixeltable repository: pixelmemory # workflow: release.yml environment: pypi diff --git a/README.md b/README.md index d44e61a..90e8654 100644 --- a/README.md +++ b/README.md @@ -208,11 +208,47 @@ All examples use the context-based API and are ready to run: ## Migrating from 0.1.x -0.2.0 runs on Pixeltable 0.7.17+. On 0.5.6+ the Document, Audio and Video -memories raised on construction, so most of 0.1.x did not work. Upgrade with +0.2.0 requires Python 3.11+ and Pixeltable 0.7.17+. It introduces a +context-based API. After the release is published, upgrade with `pip install -U pixelmemory`. -Three things changed for callers: +### From the published 0.1.0 package + +The 0.1.0 wheel on PyPI has a conversation-only API. Its constructor, insertion +arguments and search result format differ from 0.2.0: + +| Published 0.1.0 | 0.2.0 | +| --- | --- | +| `Memory()` or `Memory(embedding_model="...")` | `Memory(context=[Text(id="content", embed_model="...")], namespace="user_123_memory")` | +| `memory.add(messages, user_id="user_123")` | `memory.add(memory.Entry(content=conversation))` | +| `memory.search(query, user_id="user_123")["results"]` | `memory.search(query)` returns a list; use a separate namespace for each user | +| Result keys `memory` and `similarity` | Result keys `text` and `score`, plus `context_id` | + +For example, to store the same conversation text: + +```python +from pixelmemory import Memory +from pixelmemory.context import Text + +memory = Memory([Text(id="content")], namespace="user_123_memory") +messages = [{"role": "user", "content": "I enjoy programming."}] +conversation = " ".join(f"{m['role']}: {m['content']}" for m in messages) +memory.add(memory.Entry(content=conversation)) +for result in memory.search("programming"): + print(result["text"], result["score"]) +``` + +Existing `pixelmemory_` tables remain separate; 0.2.0 does not +automatically import their rows. Export or back up their `timestamp`, `memory` +and `metadata` columns through Pixeltable before migrating data into a new +namespace. Declare additional contexts if you want to retain those fields; +use raw table/view queries to retrieve source metadata alongside search hits. + +### From the unreleased context-based repository API + +If you installed the repository rather than the PyPI wheel, the context API +was already present. Its Document, Audio and Video pipelines used removed +Pixeltable iterator arguments. The relevant changes are: - **Python 3.11+ is required.** Pixeltable dropped 3.10 in 0.7.2. - **Two splitter parameter dataclasses are renamed.** `AudioSplitterParams` @@ -237,8 +273,8 @@ results = (chunk_view.order_by(sim, asc=False).limit(3) results = memory.search(query, on="report", limit=3) ``` -`Memory(...)`, `memory.Entry`, `memory.add()` and the attribute passthrough -keep the same API. Use `required=False` for a nullable context; its Entry field +For that repository API, `Memory(...)`, `memory.Entry`, `memory.add()` and the +attribute passthrough keep the same shape. Use `required=False` for a nullable context; its Entry field can be omitted and defaults to `None`. Optional contexts can also be embedded. Embedding index names are scoped to each context so multiple embedded fields diff --git a/RELEASING.md b/RELEASING.md index 45d6143..8f1e99c 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -28,7 +28,8 @@ Publishing uses PyPI Trusted Publishing. PyPI mints a short-lived credential from the workflow's OIDC identity, so there is no long-lived secret to leak, rotate, or paste into a shell. -One-time setup, on PyPI under **Manage project -> Publishing -> Add a pending publisher**: +One-time setup, on PyPI under **Manage project -> Publishing**, add a GitHub +publisher to the existing `pixelmemory` project: | field | value | |---|---|