ORMs, LangChain, LlamaIndex, and Abstraction Boundaries

ORMs and AI frameworks can accelerate integration, loaders, chunkers, provider adapters, and workflow composition. They do not remove responsibility for schema, SQL, indexes, authorization, transactions, deletion, evaluation, or operations. Define a narrow retrieval interface, keep migration DDL and critical SQL reviewable, inspect generated queries, and pin framework versions behind contract tests.

What will you be able to do?

Decide where an abstraction adds value.
Preserve a stable application-owned retrieval contract.
Inspect ORM-generated pgvector queries and plans.
Avoid framework-owned schema drift.
Replace a framework without rewriting product policy.

What should the application own?

Own document/chunk/model identity, tenant and permission policy, migration files, embedding provenance, retrieval inputs/outputs, citation semantics, evaluation, and deletion. A framework adapter may implement that interface, but should not silently invent IDs, collections, metadata shapes, or distance conversions.

python

class RetrievalRepository(Protocol):
    def search(
        self,
        policy: AuthorizedPolicy,
        query: QueryEmbedding,
        limit: int,
    ) -> list[RetrievedChunk]: ...

This contract can be backed by direct psycopg SQL, SQLAlchemy, LangChain, LlamaIndex, or another tool. Keep one direct-SQL reference implementation for clarity and debugging.

What must you inspect?

table and column types plus vector dimensions;
metric/operator and operator class;
placement of metadata and authorization filters;
candidate and result limits;
async/sync connection use and pool ownership;
transaction scope and deletion behavior;
distance versus similarity conversion;
generated SQL and EXPLAIN plan;
framework telemetry and data sent externally.

How do you verify it?

Run the same fixtures and golden queries through direct SQL and the framework adapter. Assert ordered IDs, distances within tolerance, tenant denial, deletion, model identity, timeouts, and plan expectations. Upgrade one version at a time and rerun contract plus retrieval-regression tests.

What breaks in production?

A convenience vector store creates an ungoverned schema.
Metadata filters are applied after global retrieval.
Distance is interpreted as similarity.
Framework upgrades change defaults.
Two libraries create separate connection pools per process.

AI pair-work prompt

Audit this ORM/AI-framework vector integration [code and generated SQL]. Map every abstraction to actual PostgreSQL schema, query, transaction, pool, filter, metric, deletion, and external call. Propose a stable repository contract and direct-SQL parity tests.

Verification contract: No framework upgrade ships until generated SQL, plans, security tests, and golden retrieval results pass against the pinned baseline.

Check your understanding

What policy should never be owned only by a framework?
Why retain a direct-SQL reference?
List five contract tests for a vector-store adapter.

Official references

ORMs, LangChain, LlamaIndex, and Abstraction Boundaries

What should the application own?

python

class RetrievalRepository(Protocol):
    def search(
        self,
        policy: AuthorizedPolicy,
        query: QueryEmbedding,
        limit: int,
    ) -> list[RetrievedChunk]: ...

This contract can be backed by direct psycopg SQL, SQLAlchemy, LangChain, LlamaIndex, or another tool. Keep one direct-SQL reference implementation for clarity and debugging.

What must you inspect?

table and column types plus vector dimensions;

metric/operator and operator class;

placement of metadata and authorization filters;

candidate and result limits;

async/sync connection use and pool ownership;

transaction scope and deletion behavior;

distance versus similarity conversion;

generated SQL and EXPLAIN plan;

framework telemetry and data sent externally.

AI pair-work prompt

Audit this ORM/AI-framework vector integration [code and generated SQL]. Map every abstraction to actual PostgreSQL schema, query, transaction, pool, filter, metric, deletion, and external call. Propose a stable repository contract and direct-SQL parity tests.

Verification contract: No framework upgrade ships until generated SQL, plans, security tests, and golden retrieval results pass against the pinned baseline.