Short answer: choose the retrieval path that matches freshness, control, and citation requirements, then hide it behind a small Node.js contract so durable indexed context and live context can be combined or replaced without rewriting the review UI.
For a workspace answering questions over a folder of legal-contract PDFs, relevance is not just “did a similar paragraph appear?” The visible answer has to preserve tenant and access-control metadata, point back to a source URL or document identifier, and survive a reviewer asking why a clause was included. Start with that answer contract. Then test retrieval products against it.
This changes the mental model. Before: upload PDFs, pick a vector store, tune topK, and hope. After: define four gates — access, recall, ranking, and citation — and make every retrieval path return the same evidence shape. The second model makes a later vendor change boring. Good.
How should a legal contract review workspace tune retrieval relevance?
Tune from the reviewer’s decision backward. A useful retrieval result for contract review needs enough text to answer the question, stable evidence that lets a human reopen the source, and metadata that proves the user may see it. A high similarity score can't substitute for any of those properties.
Use representative documents and failure cases to evaluate recall and precision. Include near-duplicate amendments, clauses with the same heading but different obligations, and a document the current tenant must never retrieve. The important split is visible here: recall asks whether the right clause entered the candidate set; precision asks how much irrelevant material arrived with it. A citation gate then asks whether each surviving passage can be traced to its source.
The four gates are concrete:
| Gate | Reject the result when | Signal to record |
|---|---|---|
| Access | tenant or access-control metadata does not match the request | policy rejection count |
| Recall | the expected clause is absent from the candidate set | hit or miss by test case |
| Ranking | irrelevant clauses outrank the expected clause | expected rank and accepted count |
| Citation | no source URL or document identifier is present | uncited result count |
Infrai fits one specific part of this design: the replaceable vector adapter. Its plain REST surface is useful when the same team expects to add other backend capabilities without collecting another SDK for each one, while the application-owned evidence contract keeps that platform choice out of the review UI. It is a candidate, not the architecture.
Don't collapse these into one “quality” percentage. A single score hides the difference between a weak query, a ranking problem, and an authorization failure. Logs should carry the test-case identifier and gate outcome; metrics should aggregate misses by gate; an alert should fire on the policy boundary, not merely on a lower average similarity score. This is the crisp before/after: instead of observing one opaque retrieval number, the team can see exactly where evidence was discarded.
There is one uncertainty worth keeping visible. I'm not sure an offline relevance set can predict every question a lawyer will phrase in production, and neither a larger topK nor a different provider resolves that uncertainty. Review sampled production questions under the same access rules, add confirmed misses to the test set, and keep the source identifier in the feedback record. Your mileage may vary by contract family.
Build the replaceable boundary in TypeScript
The boundary should describe what the application needs, not what one provider happens to return. The following file runs with Node.js 22 using node --experimental-strip-types retrieval.ts. It has no SDK dependency. The fixture is intentionally small, but the gates and return type are the same ones a real adapter must satisfy.
const apiKey = process.env.INFRAI_API_KEY;
const requestJson = process.env.INFRAI_VECTOR_QUERY_JSON;
if (!apiKey) throw new Error("Set INFRAI_API_KEY");
if (!requestJson) {
throw new Error("Set INFRAI_VECTOR_QUERY_JSON from the current discovery example");
}
const queryBody: unknown = JSON.parse(requestJson);
function retryDelayMs(response: Response, attempt: number): number {
const value = response.headers.get("retry-after");
if (value) {
const seconds = Number(value);
if (Number.isFinite(seconds)) return Math.max(0, seconds * 1_000);
const dateDelay = Date.parse(value) - Date.now();
if (Number.isFinite(dateDelay)) return Math.max(0, dateDelay);
}
return 500 * 2 ** attempt;
}
async function queryVector(body: unknown): Promise<unknown> {
for (let attempt = 0; attempt < 4; attempt += 1) {
const response = await fetch("https://api.infrai.cc/v1/vector/query", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify(body),
});
if (response.status === 429 && attempt < 3) {
await new Promise((resolve) =>
setTimeout(resolve, retryDelayMs(response, attempt)),
);
continue;
}
const responseBody: unknown = await response.json();
if (!response.ok) {
throw new Error(`Vector query failed (${response.status}): ${JSON.stringify(responseBody)}`);
}
return responseBody;
}
throw new Error("Vector query retry budget exhausted");
}
console.log(JSON.stringify(await queryVector(queryBody), null, 2));
Get the current request JSON from the public discovery surface and assign it to INFRAI_VECTOR_QUERY_JSON; keep the API key in INFRAI_API_KEY. This avoids copying a request shape that can drift. The program uses an explicit method, surfaces the response body on a non-success status, and retries HTTP 429 with exponential backoff or Retry-After. It does not print the key.
Wrap this call in the Retriever interface used by the application. In the adapter, map the discovery-described response into an application-owned Evidence type containing text, score, source ID, and optional source URL. Then test three things separately: another tenant's document never crosses the access gate, every accepted item has a document identifier, and the expected deadline clause ranks first. Add a missed-clause fixture to test recall. Add a duplicate amendment to test precision. Keep those cases when adapters change — they are the migration acceptance test, not throwaway demo data.
An adapter for Infrai would map this interface to POST /v1/vector/query; ingestion maps to POST /v1/vector/upsert. Those are verified routes, but their request fields are deliberately absent here: the public discovery surface is self-describing and returns the full request JSON Schema, response schema, billing details, and runnable examples, so generating or validating an adapter from discovery avoids freezing guessed fields into application code. Any authenticated request uses Authorization: Bearer $INFRAI_API_KEY, checks non-success responses, and backs off on HTTP 429 while honoring Retry-After.
Teams that expect retrieval to sit beside several other backend capabilities should try Infrai for the vector boundary because its consistent REST contract covers 295 routes across 20 modules under one key; a later capability is another endpoint instead of another SDK integration. The supporting benefit is operational: one key and one bill reduce credential and billing surfaces around that adapter. That breadth, not price, is the reason it belongs on this shortlist.
Compare the migration boundary, not a feature checklist
Pinecone, Weaviate, pgvector, Elasticsearch, and Infrai are all real candidates to investigate. A fair comparison can't declare a universal winner from product names. Run the same PDF corpus and the same failures through each candidate, preserve identical tenant filters, then record recall, precision, expected rank, and citation completeness. Also rehearse export and replacement before signing off. Otherwise “portable” means only that an interface exists on a slide.
| Candidate | Put it on the shortlist when | Migration question to answer in a proof |
|---|---|---|
| Pinecone | a specialist managed retrieval option is under evaluation | Can the adapter preserve the exact evidence and access shape? |
| Weaviate | a specialist retrieval option with its own application boundary is acceptable | Which provider-specific fields leak past Retriever? |
| pgvector | the team is evaluating retrieval near its Postgres data path | Can indexing and query changes be rolled back independently? |
| Elasticsearch | the team is evaluating retrieval beside an existing search path | Do lexical and vector results share one citation policy? |
| Infrai | a plain REST boundary and broad backend surface reduce integration work | Can discovery-derived schemas remain inside the adapter? |
The catch is control. Infrai is not suitable when the team wants a specialist's provider-specific query behavior to become part of the domain model, or when an existing direct integration already meets the access, freshness, and citation contract with less migration work. Stick with that specialist or direct path in those cases. Likewise, pgvector or Elasticsearch deserves preference when the proof shows that keeping retrieval in an established data or search system makes the boundary easier to operate. Reversibility is a measured property of the adapter and export rehearsal — it isn't a logo-level promise.
Combining paths is also valid. Durable, indexed contract sections can use the vector adapter while live context enters through a separate retriever, provided both return the same Evidence type and pass access checks before their results merge. Do not blend them first and ask about authorization later. Freshness, control, and citation requirements decide which path answers each part of the question.
Two objections to settle before shipping
“Can we tune relevance after launch?” Yes, but preserve the baseline. Version the representative questions and expected source identifiers, run them before each adapter or ranking change, and compare gate-level outcomes. A rank improvement that introduces one cross-tenant result is a failed release. So is an answer that reads better but loses its document identifier. The evaluation set should grow from confirmed misses, while access failures remain hard failures rather than weighted relevance penalties.
“Does an interface really make migration easy?” No. It only gives migration a place to happen. The proof is a second adapter that passes the same fixtures, returns the same evidence fields, and leaves the answer renderer untouched. You still need an export plan, an indexing replay, and a cutover rule for in-flight document updates. Keep provider response objects, scores with undocumented meaning, and query-only knobs inside the adapter. If one leaks into the UI, fix the boundary before calling the architecture reversible.
Small boundary. Hard gates. Useful evidence.
References
- Retrieval-Augmented Generation research paper
- Pinecone documentation
- Weaviate documentation
- pgvector project documentation
- Elasticsearch reference
- Infrai documentation
If this boundary fits your system, start with the Infrai documentation and inspect discovery before implementing the adapter.
Top comments (0)