Vector Metadata Contract

{
  "id": "extraction_123:semantic:00042",
  "text": "Chunk text to embed...",
  "metadata": {
    "tenant_id": "customer_abc",
    "document_id": "source_system_doc_789",
    "extraction_id": "extraction_123",
    "job_id": "job_456",
    "source_url": "s3://customer-bucket/legal/filing.pdf",
    "filename": "filing.pdf",
    "page": 12,
    "chunk_strategy": "semantic",
    "chunk_index": 42,
    "schema_version": "extract-config-v3",
    "created_at": "2026-06-30T00:00:00Z"
  }
}

def vector_records(extraction_result, *, tenant_id, document_id, source_url):
    extraction_id = extraction_result["extraction_id"]
    chunking = extraction_result.get("extensions", {}).get("chunking", {})

    for strategy, chunks in chunking.items():
        if not isinstance(chunks, list):
            continue

        for index, chunk in enumerate(chunks):
            text = chunk.get("text") or chunk.get("content") or chunk.get("markdown")
            if not text:
                continue

            yield {
                "id": f"{extraction_id}:{strategy}:{index:05d}",
                "text": text,
                "metadata": {
                    "tenant_id": tenant_id,
                    "document_id": document_id,
                    "extraction_id": extraction_id,
                    "job_id": extraction_result.get("job_id"),
                    "source_url": source_url,
                    "filename": extraction_result.get("filename"),
                    "page": chunk.get("page") or chunk.get("page_number"),
                    "chunk_strategy": strategy,
                    "chunk_index": index,
                },
            }

records = list(vector_records(
    result,
    tenant_id="customer_abc",
    document_id="loan_file_789",
    source_url="s3://customer-bucket/loan_file.pdf",
))

texts = [record["text"] for record in records]
vectors = embed(texts)  # Use your approved embedding provider.

for record, vector in zip(records, vectors):
    vector_db.upsert(
        id=record["id"],
        vector=vector,
        metadata=record["metadata"],
    )