feat(dynamodb): per-document TTL support and automatic provisioning (#22)

[shivamm-gupta]

Fixes #22

Context & Motivation

Ephemeral vector documents (session context, temporary cache entries, expiring credentials, or transient user uploads) often require automated lifecycle management. Storing them indefinitely in DynamoDB increases storage costs and necessitates costly custom scan-and-delete cleanup jobs.

This PR adds native Time to Live (TTL) support for documents in dynavec:

• Allows setting ttl_seconds per document (on Document or dict) or as a batch default on db.upsert(...) and ns.upsert(...).
• Dynavec automatically calculates the Unix epoch expiration timestamp (int(time.time() + ttl_seconds)) and persists it into DynamoDB's ttl attribute.
• Automatically enables TTL on the DynamoDB table during provisioning (ensure_table, ensure_ttl, and provision_all).
• Supports reading back ttl in SearchResult.ttl / .to_dict() and preserves existing TTL across updates when not overridden.

Changes

• src/dynavec/config.py: Added dynamodb_enable_ttl: bool = True and dynamodb_ttl_attribute: str = "ttl" to DynavecConfig.
• src/dynavec/models.py:
  • Added ttl_seconds: int | None = None to Document dataclass with positive-value validation.
  • Added ttl: int | None = None to SearchResult dataclass and .to_dict().
• src/dynavec/stores/dynamodb.py:
  • Defined TTL_ATTR = "ttl".
  • Updated _build_item and check_item_size to handle ttl.
  • Updated put_many and put_versioned to accept and write ttl attributes.
  • Updated get_many and get_versioned to hydrate ttl.
• src/dynavec/client.py:
  • Added ttl_seconds parameter to upsert() and update().
  • Updated _prepare to compute epoch timestamps from ttl_seconds.
  • Preserved document TTL across updates when not explicitly overwritten.
  • Hydrated ttl into SearchResult on search and get().
• src/dynavec/namespace.py: Added ttl_seconds to NamespaceView.upsert and NamespaceView.update.
• src/dynavec/provisioning.py: Added ensure_ttl and updated ensure_table to enable TTL idempotently.
• docs/iam-policy.json & README.md: Added dynamodb:DescribeTimeToLive and dynamodb:UpdateTimeToLive to IAM permissions and added documentation section for TTL usage.
• tests/test_dynamodb_ttl.py: Added 10 offline unit tests covering validation, upsert/update TTL computations, overrides, preservation, hydration, and table provisioning with moto.

Testing

• pytest tests/test_dynamodb_ttl.py - 10 passed
• pytest full test suite - all 620+ passed
• ruff check - clean

[codeforstartups]

Great feature — per-document TTL via DynamoDB's native Time-To-Live. ttl_seconds on Document / upsert() (and a batch default), computes the Unix epoch, stores it in the ttl attribute, and enables TTL on the table during provisioning. Perfect for session memory / ephemeral cache entries. IAM policy + README updated. Verified: ruff clean, 10 tests pass, CI green incl. typecheck. Merging — thanks @shivamm-gupta! 🙌