Skip to content

rust-sdk: close the ergonomics gap with the Python SDK #2278

Description

@tomz-alt

Part of #2273. Ordered checklist — the module regroup goes first (everything else touches
its paths); docs go last.

  • Module regroup: mirror Python layout — connectors::{postgres, sqlite, qdrant, lancedb, turbopuffer, doris, surrealdb, kafka, iggy, valkey, neo4j, falkordb, amazon_s3, gdrive, oci_object_storage}, resources::{file, fs, id}; ops::* and
    engine machinery stay at root. Feature gates unchanged, no re-exports (unreleased).
    Mechanical, no behavior change.
  • #[cocoindex::function(batching)] / (memo, batching) / max_batch_size = N:
    declared batch-shaped (ctx, items: Vec<T>) -> Result<Vec<U>>, called item-shaped —
    same contract as @coco.fn(batching=True). Macro generates the hidden Batched static
    wired with the hash const; (memo, batching) body receives only cache misses; extra
    params fold into per-item memo keys. Compile errors for wrong shapes.
  • context_key! macro: one line replacing the LazyLock<ContextKey<T>> ritual,
    three forms (plain / detect_change / state = fn). Name stays an explicit string —
    key names are embedded in persistent target-state keys, never derive from
    module_path!().
  • Memo guidance fix (docs + tests, no new API): (memo) bodies receive an owned
    Ctx (memo.rs:117-126) and memo_key(param = skip) needs only Any + Clone
    (memo.rs:254), so the attribute already covers non-serializable resources — rewrite
    the misleading "realistic pattern" comment in tests/pipeline.rs, add tests, document
    that manual ctx.memo is block-level only and not logic-tracked.
  • TableSchema::from_row for postgres / lancedb / qdrant / turbopuffer (only doris +
    sqlite have it): follow the sqlite impl, add runtime
    with_vector_dim("embedding", embedder.dim()), convert examples/rust/* to
    #[derive(SchemaFields)].
  • ops::sentence_transformers adopts the batching macro (after item 2): Python's op
    gets batching + memoization internally; the Rust op is a plain method today.
  • Docs truth pass (last): fix SHOWCASE.md (async App::open, DirTarget, batching
    sections), add a Rust quickstart docs page mirroring the Python text_embedding
    walkthrough, document memo_key(...) / context_key! / mount-spelling guidance.

Acceptance: examples/rust/text_embedding reads line-for-line like the Python version —
context_key! statics, derived schema, no hash constants or LazyLock<Batched> anywhere.
Each checkbox lands as its own PR.

Metadata

Metadata

Assignees

Labels

Projects

Status
Todo

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions