release: 0.38.0

[stainless-app]

Automated Release PR

0.38.0 (2026-05-13)

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

Features

• 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 (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/b924f817d2ae7be3816833327a149a3932809d61/hyperspell-0.37.0-py3-none-any.whl'

Expires at: Fri, 12 Jun 2026 03:06:54 GMT
Updated at: Wed, 13 May 2026 03:06:54 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

This PR releases v0.38.0 of the Hyperspell Python SDK, adding three new third-party integrations, a range of internal utilities, and security hardening for CI workflows.

• New integrations: granola, fathom, and linear added as valid source/provider/integration literals across all relevant API types and resource methods
• EagerIterable: New Pydantic-compatible generic type that eagerly validates any Iterable[T] upfront, preventing generator exhaustion on repeated model_dump() calls
• HYPERSPELL_CUSTOM_HEADERS: Environment variable support in both sync/async clients for injecting newline-separated key: value default headers
• deepcopy_with_paths: Replaces deepcopy_minimal with a path-targeted selective shallow copy utility; removes deepcopy_minimal from public API and tests
• ArrayFormat for multipart: extract_files/_extract_items gain an array_format parameter (brackets, indices, repeat, comma) with a new _array_suffix helper; ArrayFormat/NestedFormat type aliases moved to _types.py
• memories.update: New optional date parameter (ISO 8601) for document ranking/filtering
• memories.search: effort changed from int to Literal['minimal', 'low', 'medium', 'high']; new recency_half_life_days option in search params
• connection_list_response: New selected_count field; integration_list_response: New requires_channel_selection field; shared/resource: New folder_ancestors field
• CI security: All GitHub Actions pinned to immutable commit SHAs in ci.yml, publish-pypi.yml, and release-doctor.yml
• Bug fixes: Missing f-string prefix in _files.py TypeError message; ${SKIP_BREW:-} unbound variable fix in bootstrap script
• MCP badge URLs: Updated to use scoped package name @hyperspell/hyperspell-mcp in README
• @stdy/cli: Bumped from 0.20.2 to 0.22.1 in mock and test scripts

---

Confidence Score: 3/5 - Review Recommended

Likely safe but review recommended — this PR is a well-structured SDK release adding granola, fathom, and linear integrations along with the EagerIterable utility and CI hardening, but a pre-existing unresolved concern about _utils.py remains open. Specifically, in src/hyperspell/_utils/_utils.py around L140-151, when flattened_key is None and _array_suffix returns an empty string (for 'repeat' or 'comma' formats), an empty string '' is passed to the recursive call instead of None, which could produce malformed serialized keys in query parameter flattening. While this bug was not introduced by this PR, it remains unresolved and touches core utility logic used across the SDK.

Key Findings:

• The unresolved comment on _utils.py:L140-151 identifies a correctness issue where flattened_key=None combined with an empty _array_suffix result causes '' (empty string) to be passed recursively instead of None, potentially producing query strings with a leading separator like '.field' instead of 'field' for nested keys in repeat/comma array formats.
• The new EagerIterable Pydantic-compatible generic type is a meaningful addition that prevents generator exhaustion on repeated model_dump() calls — the approach of eagerly materializing iterables at validation time is sound and the design rationale is clear.
• The addition of granola, fathom, and linear as valid literals across source/provider/integration type definitions is a mechanical but broad change touching many files; 35/39 changed files were reviewed, giving reasonable confidence that the literal additions are consistent.
• CI security hardening changes appear to be positive improvements without obvious regressions, but the unresolved utility bug means the overall SDK serialization correctness cannot be fully vouched for without a fix or explicit confirmation that the edge case is benign.

Files requiring special attention

• src/hyperspell/_utils/_utils.py
• src/hyperspell/_utils/__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]

Release v0.38.0 of the hyperspell Python SDK introducing new API parameters, a custom headers environment variable, and internal utility improvements.

• Custom headers: Both sync and async clients now parse HYPERSPELL_CUSTOM_HEADERS (newline-delimited Key: Value) and merge into default_headers (src/hyperspell/_client.py)
• Array format control: extract_files / _extract_items gain an array_format parameter (brackets, indices, repeat, comma) controlling multipart field name suffixes (src/hyperspell/_utils/_utils.py)
• deepcopy refactor: Replaced deepcopy_minimal with deepcopy_with_paths for path-selective shallow copying; deepcopy_minimal removed from _utils exports (src/hyperspell/_files.py, src/hyperspell/_utils/__init__.py, src/hyperspell/resources/memories.py)
• New API parameters: date (ISO 8601) added to MemoryUpdateParams and memory update methods; recency_half_life_days added to Options in memory_search_params.py
• Type aliases relocated: ArrayFormat and NestedFormat moved from _qs.py to _types.py
• MCP badge URLs: Updated to scoped package name @hyperspell/hyperspell-mcp in README.md
• Scripts: Bootstrap hardened against set -u; @stdy/cli bumped to 0.22.1 in mock/test scripts
• Tests: Added coverage for array_format, deepcopy_with_paths, new API params; removed test_deepcopy.py

[entelligence-ai-pr-reviews]

Correctness: When flattened_key is None and _array_suffix returns "" (for "repeat" or "comma" formats), the new code passes flattened_key="" (empty string) to the recursive call instead of None; the downstream dict-handling branch checks if flattened_key is None to decide whether to assign key or append [key], so an empty string takes the else branch and produces a malformed key like "[fieldname]" instead of "fieldname".

🤖 AI Agent Prompt for Cursor/Windsurf

📋 Copy this prompt to your AI coding assistant (Cursor, Windsurf, etc.) to get help fixing this issue

In `src/hyperspell/_utils/_utils.py`, lines 142–144, the new expression `(flattened_key if flattened_key is not None else "") + _array_suffix(array_format, array_index)` converts a `None` flattened_key into an empty string `""` when `_array_suffix` returns `""` (e.g., for `"repeat"` or `"comma"` array formats). The recursive `_extract_items` call then sees `flattened_key=""`, which is not `None`, so the dict branch appends `[key]` instead of just using `key`, producing a leading-bracket malformed key. Fix by preserving `None` when the suffix is empty: use `(flattened_key + suffix) if flattened_key is not None else (suffix if suffix else None)` where `suffix = _array_suffix(array_format, array_index)`.