Add entities namespace and activate memory pipeline hooks (#4)

Author: ethanj

.github/workflows/publish-pypi.yml

@@ -0,0 +1,55 @@
+# Publish atomicmemory to PyPI via OIDC Trusted Publishing.
+#
+# Runs ONLY on the public mirror (atomicstrata/atomicmemory-python), which is
+# the clean release surface under the manual-snapshot sync model: this file
+# rides a snapshot PR out from am-python-internal, but the `if` guard keeps it
+# inert on the private dev repo (which has no PyPI trusted-publisher binding).
+#
+# Manual, version-gated dispatch — never on push/tag — so a routine snapshot
+# sync can never trigger a publish. The `pypi-release` environment supplies the
+# human-approval gate that the local `uv publish` workflow used to provide.
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish — must equal pyproject.toml's version and not already exist on PyPI."
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    if: github.repository == 'atomicstrata/atomicmemory-python'
+    runs-on: ubuntu-latest
+    environment: pypi-release
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Verify version matches and is unpublished
+        run: |
+          pkg_version="$(sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml | head -1)"
+          if [ "${pkg_version}" != "${{ inputs.version }}" ]; then
+            echo "::error::pyproject.toml version '${pkg_version}' != requested '${{ inputs.version }}'"
+            exit 1
+          fi
+          status="$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/atomicmemory/${pkg_version}/json")"
+          if [ "${status}" = "200" ]; then
+            echo "::error::atomicmemory ${pkg_version} is already on PyPI; bump the version first"
+            exit 1
+          fi
+          echo "Publishing atomicmemory ${pkg_version} (PyPI returned ${status} for the existence check)."
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Publish to PyPI (Trusted Publishing, with attestations)
+        uses: pypa/gh-action-pypi-publish@release/v1

AGENTS.md

@@ -49,7 +49,7 @@ Before changing code, read the relevant local files first:
 Run before opening any PR:
 
 ```bash
-uv sync
+uv sync --all-extras  # installs dev + embeddings extras; strict mypy needs them
 uv run ruff check .
 uv run ruff format --check .
 uv run mypy atomicmemory --strict

CHANGELOG.md

@@ -4,7 +4,16 @@ All notable changes to `atomicmemory` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.1.1] - 2026-06-11
+
+### Added
+- `UnsupportedOperationError` (subclass of `ProviderError`) and `InvalidScopeError` (subclass of `ValidationError`), raised where those parents were previously raised bare: a provider missing the `package` extension, and an operation missing required scope fields. Existing `except ProviderError` / `except ValidationError` handlers keep working; consumers can now catch the specific types, matching the TS SDK. Exported from the package root.
+- `AsyncMemoryProcessingPipeline` + `NOOP_ASYNC_PIPELINE` (exported from `atomicmemory.memory` alongside the existing sync type): the async-surface pipeline type used by `AsyncProviderRegistration`.
+- `EntitiesClient` / `AsyncEntitiesClient`: the `entities` namespace over `/v1/entities`, ported from the TS SDK — entity profiles, listing, detail, cascade delete, attribute triples, per-memory history, per-entity settings patching, and entity merge. Wired into `AtomicMemoryClient`/`AsyncAtomicMemoryClient` as `.entities` on the same transport config, closed with the client. Python field names match the snake_case wire directly (the TS camelCase mapping layer has no Python counterpart).
+
+### Changed
+- Registered memory pipelines now actually execute: `MemoryService`/`AsyncMemoryService` run `preprocess_ingest` (which may split one input into many; per-item results merge in order), `postprocess_ingest`, `preprocess_search`/`postprocess_search` (postprocess receives the processed request), `preprocess_get`/`postprocess_get`, and `postprocess_list`, matching the TS `MemoryService` semantics. `delete` and `package` take no pipeline. Before 1.1.1 these hooks were accepted at registration but never invoked. Hook exceptions propagate unwrapped — hooks are caller-supplied code.
+- `MemoryProcessingPipeline` hook signatures are now synchronous (the async surface uses `AsyncMemoryProcessingPipeline`). Type-hint change only for code that constructed pipelines — which received no behavior before this release.
 
 ## [1.1.0] - 2026-06-09
 

README.md

@@ -21,7 +21,7 @@ This is a Python port of the TypeScript [`atomicmemory-sdk`](https://github.com/
 
 ## Status
 
-Stable release — `1.0.0` on [PyPI](https://pypi.org/project/atomicmemory/).
+Stable release — `1.1.0` on [PyPI](https://pypi.org/project/atomicmemory/); `1.2.0` staged on main.
 
 ## Installation
 
@@ -131,6 +131,64 @@ The `client.storage` namespace mirrors the TypeScript SDK's direct storage API:
 
 Every storage request sends `Authorization: Bearer <apiKey>` and `X-AtomicMemory-User-Id`. The SDK never sends the legacy `?user_id=` URL parameter.
 
+
+## Entities
+
+The `client.entities` namespace (on `AtomicMemoryClient` and `AsyncAtomicMemoryClient`) provides typed access to the `/v1/entities` API — profiles, attributes, memory history, settings, and entity merge.
+
+```python
+from atomicmemory import AtomicMemoryClient
+
+with AtomicMemoryClient({
+    "apiUrl": "http://localhost:17350",
+    "apiKey": "server-api-key",
+    "userId": "demo",
+}) as client:
+    # fetch the synthesized profile for a user
+    profile = client.entities.profile("alice")
+    print(profile.entity_id, profile.summary)
+
+    # list all entities (paginated)
+    result = client.entities.list(page=1, page_size=20)
+    for entity in result.entities:
+        print(entity.entity_id, entity.memory_count)
+```
+
+The async surface is identical — call `await client.entities.profile("alice")` on `AsyncAtomicMemoryClient`.
+
+## Memory pipelines
+
+`MemoryProcessingPipeline` (and its async twin `AsyncMemoryProcessingPipeline`) let you attach optional pre- and post-processing hooks to any registered provider. All hook fields are `None` by default, so a pipeline with only one hook populated is valid.
+
+```python
+from atomicmemory import AtomicMemoryClient
+from atomicmemory.memory.pipeline import MemoryProcessingPipeline
+from atomicmemory.memory.registry import ProviderRegistration, default_registry
+
+def split_long_content(input):
+    # return a list of IngestInput items; here we pass through unchanged
+    return [input]
+
+def log_ingest_result(result, original_input):
+    print(f"ingested: {len(result.created)} created, {len(result.updated)} updated")
+
+pipeline = MemoryProcessingPipeline(
+    preprocess_ingest=split_long_content,   # optional — splits one input into many
+    postprocess_ingest=log_ingest_result,   # optional — runs after each per-item ingest
+)
+
+# Register the pipeline alongside a provider factory
+def my_provider_factory(config):
+    from atomicmemory.memory.provider import BaseMemoryProvider
+    # ... build and return your provider ...
+    provider = ...
+    return ProviderRegistration(provider=provider, pipeline=pipeline)
+
+default_registry.register("my_provider", my_provider_factory)
+```
+
+If `preprocess_ingest` splits one input into N items and a per-item ingest raises mid-loop, earlier items are already persisted and no merged result is returned — keep splitting pipelines idempotent.
+
 ## v1 wire contract
 
 `atomicmemory.contract.v1` is the wire codec for the v1 provider-contract encoding. The wire form is deliberately mixed-case — `Memory.createdAt`/`updatedAt` and `SearchResult.rankingScore` are camelCase; `version_id`, `observed_at`, and retrieval-receipt fields are snake_case — as pinned by the vendored `contract/CONTRACT.md`. This module is the only place that mapping lives; in-process models and provider mappers are unchanged.

RELEASING.md

@@ -0,0 +1,35 @@
+# Releasing `atomicmemory` to PyPI
+
+Publishing uses **OIDC Trusted Publishing** — no API tokens. The package is
+published from the public mirror (`atomicstrata/atomicmemory-python`), which is
+the clean release surface; development happens here in the private repo and
+reaches the mirror via a manual snapshot sync.
+
+## One-time setup (already done unless this is a fresh project)
+
+1. **PyPI Trusted Publisher** — on the `atomicmemory` project at
+   <https://pypi.org/manage/project/atomicmemory/settings/publishing/>, add a
+   GitHub publisher:
+   - Owner: `atomicstrata`
+   - Repository: `atomicmemory-python`
+   - Workflow filename: `publish-pypi.yml`
+   - Environment name: `pypi-release`
+2. **GitHub environment** — on `atomicstrata/atomicmemory-python`, create an
+   environment named `pypi-release`. Add the release approver as a required
+   reviewer to gate each publish behind a one-click approval.
+
+## Releasing a version
+
+1. Land the version bump + changelog on this repo's `main` (the `[Unreleased]`
+   CHANGELOG section becomes `[X.Y.Z] - <date>` at release time).
+2. Snapshot-sync `main` to `atomicstrata/atomicmemory-python` (single curated PR;
+   merge after its CI is green).
+3. On the mirror, run the **Publish to PyPI** workflow
+   (Actions → Publish to PyPI → Run workflow) with the exact version as input.
+   It verifies the version matches `pyproject.toml` and is not already on PyPI,
+   builds the sdist + wheel with `uv build`, and publishes via OIDC with PEP 740
+   attestations. The `pypi-release` environment prompts for approval first.
+4. Verify: `pip install atomicmemory==X.Y.Z` from a clean environment.
+
+The workflow is `workflow_dispatch`-only and guarded to run solely on the public
+mirror, so a routine snapshot sync never triggers a publish.

atomicmemory/__init__.py

@@ -17,12 +17,36 @@
 from atomicmemory.core.errors import (
     AtomicMemoryError,
     ConfigError,
+    InvalidScopeError,
     NetworkError,
     NotInitializedError,
     ProviderError,
     RateLimitError,
+    UnsupportedOperationError,
     ValidationError,
 )
+from atomicmemory.entities import (
+    AsyncEntitiesClient,
+    DeletedCounts,
+    DeleteEntityResult,
+    EntitiesClient,
+    EntitiesClientConfig,
+    EntitiesClientError,
+    EntityAttribute,
+    EntityCard,
+    EntityDetail,
+    EntityListResult,
+    EntityProfile,
+    EntityProfileBlock,
+    EntityRelation,
+    EntitySettings,
+    EntitySummary,
+    EntityType,
+    MemoryHistory,
+    MemoryHistoryEntry,
+    MergedCounts,
+    MergeEntitiesResult,
+)
 from atomicmemory.memory.capability_profiles import (
     CapabilityGap,
     CapabilityProfile,
@@ -110,6 +134,7 @@
     "ArtifactRange",
     "ArtifactRef",
     "AsyncAtomicMemoryClient",
+    "AsyncEntitiesClient",
     "AsyncMemoryClient",
     "AsyncProviderStatus",
     "AsyncStorageClient",
@@ -127,6 +152,21 @@
     "DeleteArtifactOptions",
     "DeleteArtifactPolicy",
     "DeleteArtifactResult",
+    "DeleteEntityResult",
+    "DeletedCounts",
+    "EntitiesClient",
+    "EntitiesClientConfig",
+    "EntitiesClientError",
+    "EntityAttribute",
+    "EntityCard",
+    "EntityDetail",
+    "EntityListResult",
+    "EntityProfile",
+    "EntityProfileBlock",
+    "EntityRelation",
+    "EntitySettings",
+    "EntitySummary",
+    "EntityType",
     "FieldFilter",
     "FieldFilterOp",
     "FilecoinDirectStorageNotSupportedError",
@@ -140,15 +180,20 @@
     "IngestInput",
     "IngestResult",
     "Insight",
+    "InvalidScopeError",
     "ListRequest",
     "ListResultPage",
     "Memory",
     "MemoryClient",
+    "MemoryHistory",
+    "MemoryHistoryEntry",
     "MemoryKind",
     "MemoryNamespaceConfig",
     "MemoryRef",
     "MemoryVersion",
     "MemoryVersionEvent",
+    "MergeEntitiesResult",
+    "MergedCounts",
     "Message",
     "MessageIngest",
     "MessageRole",
@@ -179,6 +224,7 @@
     "StoredArtifact",
     "TextIngest",
     "UnsupportedCapabilityError",
+    "UnsupportedOperationError",
     "ValidationError",
     "VerbatimIngest",
     "VerificationResult",

atomicmemory/_version.py

@@ -4,4 +4,4 @@
     __version__: The current package version string (PEP 440).
 """
 
-__version__ = "1.1.0"
+__version__ = "1.1.1"