release: 0.38.0

[stainless-app]

Automated Release PR

0.38.0 (2026-06-13)

Full Changelog: v0.37.0...v0.38.0

Features

• api: api update (22cdd86)
• api: api update (eeb82b7)
• api: api update (02ef637)
• api: api update (e991d68)
• api: api update (a95dee2)
• api: api update (e160f73)
• api: api update (58c8d7c)
• api: api update (42d3c82)
• api: api update (edd9b41)
• api: api update (cc26c43)
• api: api update (aa0cc75)
• api: api update (335d028)
• api: api update (3b25c10)
• api: api update (92fd43a)
• api: api update (7a8e495)
• api: manual updates (5e31b8a)
• api: manual updates (cb78a3e)
• api: manual updates (23c9221)
• internal/types: support eagerly validating pydantic iterators (e47301a)
• support setting headers via env (eba0398)

Bug Fixes

• client: add missing f-string prefix in file type error message (6dbd3ec)
• use correct field name format for multipart file arrays (0f569cc)

Performance Improvements

• client: optimize file structure copying in multipart requests (c28640c)

Chores

• internal: more robust bootstrap script (d4a39dc)
• internal: reformat pyproject.toml (19a83c3)
• tests: bump steady to v0.22.1 (7d67d91)

---

This pull request is managed by Stainless's GitHub App.

The semver version number is based on included commit messages. Alternatively, you can manually set the version number in the title of this pull request.

For a better experience, it is recommended to use either rebase-merge or squash-merge when merging this pull request.

🔗 Stainless website
📚 Read the docs
🙋 Reach out for help or questions

[stainless-app]

🧪 Testing

To try out this version of the SDK:

pip install 'https://pkg.stainless.com/s/hyperspell-python/22cdd8677c2d30fad4ebc6fe97715fcf01628506/hyperspell-0.37.0-py3-none-any.whl'

Expires at: Mon, 13 Jul 2026 21:32:07 GMT
Updated at: Sat, 13 Jun 2026 21:32:07 GMT

[canaries-inc]

🐤 Canary Summary

This PR is a Python SDK release with no UI/UX changes affecting end users:

• Version bump to 0.38.0 across all configuration files
• Added date parameter to memories API for backend ranking/filtering
• Updated API type definitions and test coverage
• No user-facing UI components or changes present

---

---

View PR tests on Canary

[canaries-inc]

🐤 Canary Proposed Tests

No testable user journeys found for this PR.

[entelligence-ai-pr-reviews]

---

Confidence Score: 5/5 - Safe to Merge

Safe to merge — this PR is a release bump to version 0.38.0 and the automated review found no issues across the reviewed files. No logic changes, security concerns, or correctness problems were identified, and there are no unresolved pre-existing comments to carry forward. The PR appears to be a standard version release with clean diffs.

Key Findings:

• No review comments were generated by the automated analysis, indicating no detectable logic, security, or correctness issues in the changed files.
• Zero critical, significant, or medium-severity issues were flagged by the heuristic analysis, consistent with a version bump or release preparation PR.
• Coverage of 3/8 changed files leaves some files unreviewed, but for a release PR this is a low-risk gap — typically release commits touch changelogs, version files, and lock files which are low-risk by nature.

[entelligence-ai-pr-reviews]

EntelligenceAI PR Summary

Refactors memory and evaluation API types to use granular response models and expands the Hyperdoc document tree representation across shared types.

• Adds GET /evaluate/queries endpoint with EvaluateListQueriesParams and EvaluateListQueriesResponse paginated type
• Introduces dedicated MemoryGetResponse and MemoryListResponse models replacing generic Memory/Resource shared types
• Removes Resource and Notification from shared exports; retains only Metadata and QueryResult
• Rewrites metadata.py with a new Source model and simplified Metadata structure aligned to Hyperdoc node annotation spec (ENG-1390)
• Massively expands QueryResult with a discriminated Document union covering 12 document kinds and 25+ recursive block node types, plus a new Provenance model
• Updates .stats.yml endpoint count (30 → 31) and refreshes spec/config hashes
• Documents all changes in CHANGELOG.md under v0.38.0

---

Confidence Score: 3/5 - Review Recommended

Likely safe but review recommended — this release PR successfully refactors memory and evaluation API types with dedicated MemoryGetResponse/MemoryListResponse models and adds the EvaluateListQueriesParams endpoint, representing clean API surface improvements. However, a pre-existing unresolved correctness concern in src/hyperspell/_utils/_utils.py around flattened_key=None being passed as an empty string "" to recursive calls (when _array_suffix returns "" for repeat/comma formats) remains open and is not introduced by this PR but still unaddressed. Additionally, a nit-level maintainability gap exists where Source is declared in __all__ in shared/metadata.py but not re-exported through shared/__init__.py, creating a discoverability inconsistency in the public API.

Key Findings:

• Pre-existing unresolved bug in _utils.py L140-151: when flattened_key is None and _array_suffix returns "" (for repeat/comma serialization formats), the recursive call receives flattened_key="" (empty string) instead of None, which could silently produce malformed query parameter keys for array-type fields.
• The Source type in src/hyperspell/types/shared/metadata.py is listed in __all__ but not re-exported through shared/__init__.py or the top-level types/__init__.py, meaning consumers cannot import it via the standard package path despite it being part of the declared public interface.
• The core refactoring — removing Resource and Notification from shared exports and introducing granular response models like MemoryGetResponse, MemoryListResponse, and EvaluateListQueriesResponse — is structurally sound and follows good API design principles for SDK versioning.

Files requiring special attention

• src/hyperspell/_utils/_utils.py
• src/hyperspell/types/shared/metadata.py
• src/hyperspell/types/shared/__init__.py

[entelligence-ai-pr-reviews]

Releases v0.38.0 with a new date field on the memories update endpoint and a targeted deep copy utility replacing the previous full-copy approach in multipart requests.

• Added date: str | datetime | None parameter to sync/async memories.update() and MemoryUpdateParams
• Introduced deepcopy_with_paths in src/hyperspell/_files.py for selective container deep copying along specified key paths
• Removed deepcopy_minimal from src/hyperspell/_utils/_utils.py and its export from src/hyperspell/_utils/__init__.py
• Updated src/hyperspell/resources/memories.py to use deepcopy_with_paths with ['file'] path in both sync and async upload methods
• Added 8 new tests in tests/test_files.py covering deepcopy_with_paths and mutation-safety with extract_files
• Removed tests/test_deepcopy.py along with the deprecated utility
• Version bumped in pyproject.toml, _version.py, and .release-please-manifest.json; OpenAPI spec hash refreshed in .stats.yml

[entelligence-ai-pr-reviews]

Releases hyperspell v0.38.0 with an API enhancement, a deep copy performance improvement, and a test dependency update.

• Added optional date field (Union[str, datetime], ISO 8601) to MemoryUpdateParams and sync/async update methods in memories.py
• Replaced deepcopy_minimal (removed from _utils/_utils.py and _utils/__init__.py) with the new deepcopy_with_paths utility in _files.py, which shallow-copies only containers along specified key paths
• Updated memories.py upload methods to use deepcopy_with_paths imported from _files instead of _utils
• Bumped @stdy/cli from 0.20.2 to 0.22.1 in scripts/mock and scripts/test
• Updated OpenAPI spec URL/hash in .stats.yml
• Removed tests/test_deepcopy.py; added TestDeepcopyWithPaths tests in tests/test_files.py
• Version bumped to 0.38.0 in pyproject.toml, _version.py, and .release-please-manifest.json

[entelligence-ai-pr-reviews]

File: src/hyperspell/types/shared/query_result.py

New Provenance types declared in __all__ but not re-exported from shared __init__.py

src/hyperspell/types/shared/__init__.py only re-exports QueryResult, so Provenance, ProvenanceEntity, ProvenanceSource, and ProvenanceStep are inaccessible at hyperspell.types.shared.* or hyperspell.types.*, despite being listed in __all__.

from .metadata import Metadata as Metadata
from .resource import Resource as Resource
from .notification import Notification as Notification
from .query_result import QueryResult as QueryResult, Provenance as Provenance, ProvenanceEntity as ProvenanceEntity, ProvenanceSource as ProvenanceSource, ProvenanceStep as ProvenanceStep

Prompt to fix with AI

Copy this prompt into your AI coding assistant to fix this issue.

In file `src/hyperspell/types/shared/__init__.py`, line 6 currently reads:
  `from .query_result import QueryResult as QueryResult`

Four new classes — `Provenance`, `ProvenanceEntity`, `ProvenanceSource`, `ProvenanceStep` — were added to `query_result.py` and listed in its `__all__`, but they are not re-exported here. Add them to the import on line 6:
  `from .query_result import QueryResult as QueryResult, Provenance as Provenance, ProvenanceEntity as ProvenanceEntity, ProvenanceSource as ProvenanceSource, ProvenanceStep as ProvenanceStep`

Then, in `src/hyperspell/types/__init__.py` line 7, extend the `from .shared import ...` line to also include the four new names so they are accessible at the top-level `hyperspell.types` namespace.

[entelligence-ai-pr-reviews]

File: src/hyperspell/types/shared/query_result.py

Export Provenance types from shared/init.py

Provenance, ProvenanceEntity, ProvenanceSource, and ProvenanceStep are listed in __all__ here but src/hyperspell/types/shared/__init__.py only re-exports QueryResult, making the new types unreachable via from hyperspell.types import Provenance or from hyperspell.types.shared import Provenance.

from .query_result import QueryResult as QueryResult, Provenance as Provenance, ProvenanceEntity as ProvenanceEntity, ProvenanceSource as ProvenanceSource, ProvenanceStep as ProvenanceStep

Prompt to fix with AI

Copy this prompt into your AI coding assistant to fix this issue.

In file `src/hyperspell/types/shared/__init__.py`, line 6 currently reads:

    from .query_result import QueryResult as QueryResult

Replace it with:

    from .query_result import QueryResult as QueryResult, Provenance as Provenance, ProvenanceEntity as ProvenanceEntity, ProvenanceSource as ProvenanceSource, ProvenanceStep as ProvenanceStep

Then in `src/hyperspell/types/__init__.py`, line 7, extend the `from .shared import ...` line to also include `Provenance as Provenance, ProvenanceEntity as ProvenanceEntity, ProvenanceSource as ProvenanceSource, ProvenanceStep as ProvenanceStep`, so these new types are accessible via `from hyperspell.types import Provenance` as expected for a public SDK.

[entelligence-ai-pr-reviews]

File: src/hyperspell/types/shared/metadata.py

Export Source through the shared and types package __init__.py

Source is declared in __all__ but shared/__init__.py only re-exports Metadata, and types/__init__.py only imports Metadata from .shared — so from hyperspell.types import Source or from hyperspell.types.shared import Source both fail, forcing users to reach into the internal metadata module.

Prompt to fix with AI

Copy this prompt into your AI coding assistant to fix this issue.

In src/hyperspell/types/shared/__init__.py, add `from .metadata import Source as Source` alongside the existing Metadata import. Then in src/hyperspell/types/__init__.py, update the import on line 6 from `from .shared import Metadata as Metadata, QueryResult as QueryResult` to also include `Source as Source`. This ensures callers can do `from hyperspell.types.shared import Source` or `from hyperspell.types import Source` rather than having to use the internal path `from hyperspell.types.shared.metadata import Source`.