# AGENTS.md: Pinecone

## Setup
- Client created once with `PINECONE_API_KEY` from env. Index names and hosts come from config; target an index by host (`pc.Index(host=...)`) in production.
- Index dimension and metric must match the embedding model. If the index uses integrated embedding/inference, send text records and let Pinecone embed; don't mix in client-side vectors from another model.

## Data model
- Use namespaces for multitenancy (one per tenant or workspace). Every query sets the namespace; never query across tenants.
- Record ids are deterministic (`<docId>#<chunkNo>`), so re-ingestion overwrites instead of duplicating.
- Metadata: small, flat, filterable fields (`source`, `doc_id`, `updated_at`, `lang`). Keep chunk text in metadata only if size limits allow; otherwise store it in your DB keyed by id.

## Operations
- Upsert in batches (around 100-1000 records or per the SDK's limits), with retries on 429/5xx.
- Delete by id prefix or metadata filter when a document is removed; ingestion must be idempotent.
- Query: `top_k` small (5-50), `include_metadata=True`, metadata `filter` for permissions and freshness. Rerank (Pinecone rerank or your own) before sending to an LLM.
- Writes are eventually consistent; don't assume a just-upserted record is instantly queryable in tests.

## Don't
- Don't delete or recreate indexes, or delete whole namespaces, without approval.
- Don't run tests against the production index; use a dedicated test index or mock the client.

## Done
Unit tests mock the client; an optional integration test runs against a test index when `PINECONE_TEST_INDEX` is set.