> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aperium.apps.hillspire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Qdrant Contracts

> Give agents read-only hybrid search over a Qdrant legal-contracts collection, with typed metadata filters and full-text relevance.

The Qdrant Contracts connector gives agents **read-only hybrid search** over a Qdrant collection of legal-contract records. The collection is built and populated by an external ingestion pipeline; this connector only queries it. Aperium never writes to the collection and exposes no ingestion tools.

Search is hybrid: the collection carries a **dense** vector (OpenAI `text-embedding-3-small`) and a **sparse** BM25 vector, and free-text queries fuse both with reciprocal-rank fusion. Structured metadata filters compile to native Qdrant filters with exact counts.

## What you'll need

* A **Qdrant instance** already populated with the legal-contracts collection by your ingestion pipeline.
* The **collection name** and the instance's **URL**.
* A **Qdrant API key** for that instance.
* An **OpenAI API key** for computing dense query embeddings at search time.

This is a **tenant-wide** integration: an admin enters the credentials once and every user in the tenant queries through them. There is no per-user credential.

## How auth works

Qdrant Contracts uses a **direct-credential** admin form. You provide four values:

* **Qdrant URL** and **collection name** — stored as non-secret connection metadata.
* **Qdrant API key** and **OpenAI API key** — stored encrypted; Aperium's plugin code never sees the raw keys.

<Info>
  Describe these credentials by their shape only — never paste real key values into shared docs or tickets. Aperium encrypts the two API keys at rest and injects them at call time.
</Info>

Aperium does not run a Qdrant auth probe when you save; the credentials are first exercised on a real tool call. The host still applies its URL/DNS/SSRF checks before storing the URL.

## Setup

<Steps>
  <Step title="Confirm the collection exists">
    Make sure your external pipeline has already created and populated the Qdrant collection with the dense (`text-embedding-3-small`) and sparse (BM25) named vectors and the contract metadata payloads. This connector does not build or index anything.
  </Step>

  <Step title="Open the Qdrant Contracts form in Aperium">
    Open the **admin onboarding flow** (first sign-in) or the **Admin Console's MCP Servers tab** (any time after), and open the **Connect Aperium to Qdrant Contracts** form.
  </Step>

  <Step title="Enter the URL, collection, and keys">
    Fill in the **Qdrant URL**, **collection name**, **Qdrant API key**, and **OpenAI API key**, then save. Aperium stores the URL and collection as metadata and the two keys encrypted against your tenant.
  </Step>
</Steps>

## What agents can do

Two read tools, no writes:

* **Search contract records.** Filter by typed metadata fields (compiled to a native Qdrant filter with exact count-API totals) and optionally pass a free-text query. Free text routes through the hybrid dense + BM25 pipeline fused by reciprocal-rank fusion; totals are exact when the candidate pool exhausts the corpus, otherwise flagged as an at-least lower bound.
* **Get contract.** Fetch a single contract's full extraction payload by filename, with fuzzy substring matching on the source filename.

## Notes

* **Read-only.** There is no write or delete tool. Ingestion, indexing, and payload changes are owned entirely by the external pipeline.
* **Key rotation.** If you rotate the Qdrant or OpenAI key, re-open the form and paste the new value; the connection continues under the same URL and collection.
* **Embedding cost.** Every free-text (relevance) query computes an OpenAI embedding, so those queries incur OpenAI usage. Pure metadata-filter queries do not.