# 723. SGMP QA Vector Retrieval

## Goal

Store curated question, answer SQL, answer text, and their combined retrieval
document in `SGMP_POC`.  Retrieve the top-K closest examples for a new question
and pass the returned context to the Text2SQL prompt in a later application
integration.

## Security boundary

- IAM identity: `sgmp-qa-vector-api`
- IAM group: `sgmp-vector-embed-group`
- IAM policy: only `use generative-ai-text-embedding in tenancy`
- Database credential: `SGMP_POC_QA_VECTOR_CRED`, created from that dedicated
  API signing key only. It does not reuse `SGMP_POC_OCI_DEFAULT_CRED`.
- Network: HTTPS only to OCI GenAI Chicago EmbedText endpoint on port 443. The
  `SGMP_POC` ACE is provisioned once by an ADB `ADMIN` connection because an
  application schema cannot administer network ACLs.
- The private key is read from `VECTOR_OCI_API_KEY_FILE`; it is never committed,
  displayed, or persisted outside the encrypted database credential.

## Embedding contract

- Model: `cohere.embed-v4.0`
- Dimension: `1536` FLOAT32
- The current ADB `DBMS_VECTOR` OCI adapter does not forward Cohere Embed 4's
  `input_type` field; both paths therefore use the provider's compatible
  default request shape. The model and 1536-dimension vector contract remain
  fixed. Once the adapter exposes Embed 4 `input_type`, switch stored examples
  to `search_document` and incoming questions to `search_query`.
- `p_top_k` default: `3` (accepted range `1..20`)

Oracle recommends distinct document/query input types for Cohere Embed 4 RAG
flows and its default output size is 1536. See [Cohere Embed 4](https://docs.oracle.com/en-us/iaas/Content/generative-ai/cohere-embed-4.htm).

## Database API

```sql
-- Stores question + answer SQL + optional answer and returns EXAMPLE_ID.
SELECT sg_qa_vector_store(:question, :answer_sql, :answer_text) FROM dual;

-- Returns EXAMPLE_ID, QUESTION, ANSWER_SQL, ANSWER_TEXT, MODEL and distance.
DECLARE
  results SYS_REFCURSOR;
BEGIN
  results := sg_qa_vector_search(:question); -- default top 3
END;
/

-- Ready-to-insert textual context for a prompt.
SELECT sg_qa_vector_context(:question, 3) FROM dual;
```

`SG_QA_VECTOR_STORE`는 SQL `SELECT` 표현식으로 호출되는 저장 함수이므로,
함수 내부의 INSERT는 자율 트랜잭션으로 수행하고 성공 시 commit, 실패 시 rollback
한다. 이 처리가 없으면 Oracle은 `ORA-14551`로 DML을 거절한다.

## Apply

```bash
export SGMP_POC_DB_PASSWORD='...'
export SGMP_POC_WALLET_DIR='/path/to/Wallet_SGMPAIPOC'
export VECTOR_OCI_USER_OCID='...'
export VECTOR_OCI_TENANCY_OCID='...'
export VECTOR_OCI_COMPARTMENT_OCID='...'
export VECTOR_OCI_API_KEY_FILE='/secure/path/sgmp_qa_vector_api_key.pem'
export VECTOR_OCI_API_KEY_FINGERPRINT='...'
./scripts/setup-sgmp-qa-vector.sh
```

For the initial small QA corpus, exact cosine search is deliberate: it makes
results immediately verifiable. Add a vector index only after the corpus size
and recall/latency target are measured.