v2.0.0

openaivec v2.0.0 Release Notes

🎉 Highlights

openaivec 2.0 introduces DuckDB as a first-class integration, bringing persistent caching,
SQL-native AI functions, and Arrow-optimized data pipelines. This is a major release with breaking
changes to class names and configuration APIs.

---

🆕 DuckDB Integration (openaivec.duckdb_ext)

• Arrow Vectorized UDFs — register_responses_udf, register_embeddings_udf,
  register_task_udf register AI-powered functions directly in DuckDB. Rows are processed in batches
  with async concurrency and automatic deduplication — all transparent to SQL.
• Structured Output as STRUCT — Pydantic BaseModel response formats return native DuckDB
  STRUCT types with direct field access in SQL (SELECT udf(text).sentiment). Supports nested
  models, Enum, and Literal.
• Persistent Cache — DuckDBCacheBackend stores API results in a DuckDB table with LRU
  eviction. Eliminates redundant API calls across sessions.
• Vector Similarity — similarity_search() performs top-k cosine similarity queries via
  list_cosine_similarity.
• Schema → DDL — pydantic_to_duckdb_ddl() converts Pydantic models to CREATE TABLE
  statements.

⚡ Performance Improvements

• Arrow-backed Embeddings — Embedding results are now stored as pa.FixedSizeListArray<float32>
  in pandas, enabling zero-copy transfer to DuckDB/Parquet and 2-3x memory reduction.
• Zero-copy Similarity — DataFrame.ai.similarity() extracts numpy matrices directly from Arrow
  buffers.
• DuckDB JSON Serialization — _df_rows_to_json_series uses DuckDB's C++ to_json() instead of
  Python json.dumps (5-10x faster on large DataFrames).
• Batched Token Counting — count_tokens uses tiktoken.encode_batch() for 2-3x speedup.

🔄 Breaking Changes

Before (v1.x)	After (v2.0)
BatchingMapProxy	BatchCache
AsyncBatchingMapProxy	AsyncBatchCache
ProxyBase	BatchCacheBase
proxy._cache (private field)	proxy.cache (public field)
pandas_ext.set_client()	openaivec.set_client()
pandas_ext.set_responses_model()	openaivec.set_responses_model()

Migration: pandas_ext.set_* / get_* still work but emit DeprecationWarning. Use
openaivec.set_* / openaivec.get_* instead.

🏗 Architecture Changes

• CacheBackend Protocol — Runtime-checkable protocol for pluggable cache backends.
  InMemoryCacheBackend (default) and DuckDBCacheBackend both satisfy it.
• Unified Configuration — set_client, get_client, set_responses_model, etc. defined in
  _provider.py and exported from openaivec.*. Shared across pandas, DuckDB, and Spark.
• Notebook-safe Async — _run_async() helper runs coroutines from any context (including
  Jupyter) via a background thread.

📦 New Dependencies

• duckdb>=1.0.0 — core dependency
• pyarrow>=19.0.0 — core dependency

📖 Documentation

• New API reference page: duckdb_ext
• New example notebook: DuckDB customer survey sentiment analysis
• README: "Using with DuckDB" section with structured output and embedding examples
• Updated coding conventions: @dataclass for all classes, typed fields, DI via fields, of()
  factories