# Python SDK Changelog

## 0.0.12 — 2026-09-10

Install with `pip install dreamdb==0.0.12`.

- Fix GC retaining reference-mode vector pools across inline and paged Track
  indexes (#365). Upgrade or fence all collectors; already-deleted Objects and
  historical #89 metadata damage are not repaired.
- Add `rerank_pool_size` and `rerank_mode` to `Dataset.iter_vector` (#342):
  query-local partition pool and inherit/approximate/exact policy. Exact means
  exact scoring of the selected pool, not global exact recall. Unsupported graph
  overrides refuse, and missing exact capability never silently falls back.
- Include the newer Rust maintenance, Watch, tag, Stream and copy-plan core,
  without claiming Python wrappers for those new operator APIs.

The three-wheel platform policy is unchanged. See [API](/python-sdk-api.md),
[query examples](/main-features.md) and [release notes](/release-notes.md).

## 0.0.11 — 2026-09-10

Install with `pip install dreamdb==0.0.11`. The upgrade from 0.0.10 adds optional entity keys
with revision-aware operations, progressive geometry reads/writes, structured
ragged/CSR arrays, L2 and embedding identity enforcement. The shared core also
includes the storage, graph, HotShard and planning changes described in
[release notes](/release-notes.md).

New forms require compatible consumers and collectors. A stale entity revision
intentionally refuses updates; logical deletion retains history. PyPI publishes
CPython 3.8 ABI-stable wheels for macOS arm64 and Linux x86_64/aarch64, with no
source distribution or Windows/Intel Mac wheel. The installed macOS release
passed the existing geometry, entity-key and typed-array boundary suites.

## Historical documentation snapshot — 2026-09-10

At that snapshot, the site reflected core main 65c8e05: 28 specs, 66 resolved / 38 open OQs,
and 16 Draft headers. Newly documented implementations include optional entity
keys, progressive geometry, structured ragged/CSR, L2, compressed/routed/Fresh
graphs, typed HotShards, embedding identity checks, scalar path-copy updates and
hybrid planning. See [the feature guide and limits](/main-features.md).

That documentation publication was **not an SDK package release**. At the time,
Python 0.0.10 and npm 0.5.2 were the published versions and these examples required
a source build. This paragraph records that historical state, not current
registry availability.

Release history for the `dreamdb` package published on PyPI. Package versions
are independent from the DreamDB protocol and documentation-site versions.

## 0.0.10 — 2026-09-06

```bash
pip install dreamdb==0.0.10
```

This release adds typed numeric arrays and verified VideoItem reads, while
substantially reducing memory and repeated I/O in several large-data paths. It
contains the changes between
[`python-v0.0.9` and `python-v0.0.10`](https://github.com/dreamlake-ai/dreamdb-core/compare/python-v0.0.9...python-v0.0.10).

### Added

#### Typed arrays

- `Schema.add_array(...)` and `Dataset.add_array(...)` declare fixed-shape
  numeric array fields with persisted dtype, shape, byte order, C/Fortran
  layout, codec, units, semantic type, frame, and axis order.
- `Dataset.add_array_constant(...)` and `Dataset.get_array_constant(...)`
  store and retrieve one typed array for the complete timeline.
- Event and continuous arrays can be appended as NumPy arrays. Reads return
  NumPy arrays; Arrow output uses `FixedShapeTensor` rather than opaque binary
  values.
- The v1 surface supports `f32`, `f64`, signed and unsigned 8/16/32/64-bit
  integers, using either raw bytes or NPY encoding.
- Shape, dtype, layout, endianness, codec, and payload length are validated
  against the persisted declaration. NPY object loading remains disabled.

#### VideoItem reads

- `Dataset.video_item_by_key(field, item_key)` looks up metadata by an opaque
  byte key without downloading media.
- `Dataset.video_item_at(field, anchor)` returns the item containing an
  absolute timeline anchor, or `None` for a gap.
- `Dataset.read_video_item_range(field, item_key, start, end)` returns the init
  bytes and complete media fragments overlapping an item-relative half-open
  range.
- Item keys remain bytes and 64-bit anchors remain exact Python integers.
  Dataset handles also remain pinned to the Manifest resolved when opened.

### Performance and scalability

- Large Fragment Track indexes are now paged. A measured narrow query over a
  500,000-record Track reduced peak RSS from roughly 275 MB to 19 MB.
- Historical oversized inline Fragment Tracks use a bounded, content-verified
  streaming compatibility path instead of reconstructing the complete entry
  vector in memory. The same-scale measurement used roughly 4 MB peak RSS.
- Appending to a paged Fragment Track path-copies only the affected
  root-to-leaf paths and reuses untouched page addresses.
- SPLADE indexes decode directly into retained typed structures and are cached
  by verified content hash. Repeated queries avoid another index fetch and
  decode.
- Tombstone lists decode without a full generic CBOR tree. Effective tombstone
  sets are cached by exact Manifest tip and shared by concurrent readers.
- Graph-page construction preallocates from validated bounds to reduce repeated
  growth on large graphs.

### Correctness and compatibility fixes

- Unbucketed Track entries now preserve their time anchors in inline and paged
  forms, so time-range queries select and fetch the intended Item.
- Subrange reads can be verified with Bao proofs. Invalid, truncated, or
  mismatched range data fails closed; backends without outboards retain the
  whole-object compatibility path.
- Current writers keep Index Pages at the current limit, while readers continue
  to accept the larger pages emitted by earlier released writers.
- Fragment paging propagates missing or corrupt index failures instead of
  silently returning an empty result.
- The Python extension now uses PyO3 0.29.2 and removes the associated audit
  exemptions while retaining the `abi3-py38` compatibility target.
- Wheel construction excludes local `__pycache__`, `.pyc`, and `.pyo` files so
  developer-machine cache state cannot change the published artifact.

### Compatibility notes

- Python 3.8 or newer is required. This release publishes CPython ABI3 wheels
  for macOS arm64, Linux x86_64, and Linux aarch64.
- The public API baseline adds seven methods and intentionally removes none.
- Typed-array operations require NumPy. Ragged, sparse, compressed, strided,
  and device-native arrays remain outside the v1 format.
- The VideoItem methods in this release are read APIs. The Python SDK does not
  yet expose the Rust VideoItem writer.
- `read_video_item_range` materializes the selected init and Fragment bytes in
  memory; it is not a streaming media API and never crosses into the next item.

### Distribution

The release is available from
[`dreamdb 0.0.10` on PyPI](https://pypi.org/project/dreamdb/0.0.10/) as three
wheels produced by the release workflow:

- `macosx_11_0_arm64`
- `manylinux2014_x86_64`
- `manylinux2014_aarch64`

The wheels use the stable CPython 3.8 ABI and can be installed by newer
supported CPython versions on the matching platform.