# Awareness LLM Augmentation Service ## Client Connectivity and Self-Evaluation Guide ### Purpose Awareness is a model-independent control layer that evaluates an LLM's responses against a certified knowledge corpus before delivering them to the client application or user interface. ```text Client application / UI → Awareness → Client's foundation model ↓ routing · retrieval · evaluation · safety ``` The client keeps its foundation model. Awareness adds governed retrieval, evidence grounding, output evaluation, retry handling, auditability, and fail-closed behavior. ## What the service provides - Certified-domain routing and scope enforcement - Retrieval from approved, effective-dated, integrity-verified sources - Structural separation of user input and trusted evidence - Factual, safety, formatting, and confidence evaluation - Controlled retry with refreshed evidence when an answer fails evaluation - Fail-closed responses when evidence, policy, token budget, or model availability is insufficient - OpenAI-compatible chat-completions connectivity for applications and UIs - Tenant-isolated authentication, rate limits, traces, and policy settings Awareness does not replace the client's foundation model and does not make uncertified information authoritative. ## Client connectivity The client connects to the Awareness HTTPS endpoint supplied during onboarding: ```text Base URL: https:///v1 ``` The client uses a tenant-specific Awareness API key. The provider key for the foundation model is held by Awareness and is never placed in the client UI, browser code, or client request. The endpoint is supplied only after its DNS, TLS certificate, load-balancer backend, Cloud Armor policy, and Cloud Run invocation path have passed the operator smoke test. A DNS record alone does not mean the endpoint is ready. ### OpenAI-compatible request ```bash curl -sS https:///v1/chat/completions \ -H "Authorization: Bearer $AWARENESS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "", "messages": [ {"role": "user", "content": ""} ], "stream": false }' ``` The same endpoint can be used with the client's existing OpenAI SDK by changing only the `base_url` and API key. ```python from openai import OpenAI client = OpenAI( base_url="https:///v1", api_key="", ) response = client.chat.completions.create( model="", messages=[{"role": "user", "content": ""}], ) print(response.choices[0].message.content) ``` ## UI connectivity For Open WebUI or another OpenAI-compatible UI, configure: ```text API Base URL: https:///v1 API Key: tenant Awareness API key Model: registered foundation-model identifier ``` The UI must point to Awareness rather than directly to the foundation-model provider. This ensures every request passes through the augmentation and evaluation controls. ## What the client must provide Before onboarding a foundation model, the client supplies: 1. OpenAI-compatible endpoint and exact model identifier, or complete provider documentation for a custom adapter. 2. Provider credential through an approved secure exchange. 3. Model context limit, output limit, timeout, and rate-limit tier. 4. Tokenizer package/version or a reliable tokenizer endpoint. 5. Streaming requirements and response format. 6. Evaluation domain, jurisdiction, corpus version, and benchmark questions. 7. Network connectivity requirements and data-residency constraints. ## Self-evaluation workflow The client can evaluate its model without changing its application architecture: 1. Point the existing SDK or UI to the Awareness base URL. 2. Authenticate with the tenant Awareness API key. 3. Select the registered foundation-model identifier. 4. Run the supplied positive benchmark questions. 5. Run negative tests for uncertified, unsafe, ambiguous, malformed, and over-budget requests. 6. Record request IDs, latency, status, and whether the result was delivered, retried, or blocked. 7. Share the results with the Awareness service team for certification review. ### Expected outcomes | Scenario | Expected behavior | |---|---| | Certified query with verified evidence | Grounded answer is delivered | | Answer conflicts with evidence | Retry or fail-closed block | | Uncertified domain | Generation is blocked | | Unsafe or disallowed request | Generation is blocked | | Provider timeout or malformed response | No unverified answer is delivered | | Context budget exceeded | Request is blocked or safely repacked | ## Security and data handling - Each client receives an isolated tenant and environment-specific key. - API keys should be stored in the client's secret manager, not source code. - Provider credentials remain inside the Awareness runtime. - Requests should use TLS-protected HTTPS endpoints. - Logs and traces must not contain provider keys or unnecessary sensitive data. - Retention, deletion, residency, and legal-hold settings are agreed during onboarding rather than assumed. - Key rotation and incident contacts are assigned to named client owners. ## Certification boundary Production certification applies to a specific combination of foundation model, tokenizer, corpus, jurisdiction, policy version, and evaluation thresholds. A new model, corpus, or domain requires a separate certification review. Awareness is model-agnostic at the service boundary, but a model must satisfy the supported adapter contract before it can be enabled for production traffic. ## Client handoff checklist - [ ] Awareness endpoint and tenant API key received securely - [ ] Foundation model endpoint and exact model ID registered - [ ] Tokenizer and context limits verified - [ ] UI/SDK points to Awareness, not the provider directly - [ ] Positive benchmark completed - [ ] Negative fail-closed tests completed - [ ] Latency, timeout, and rate-limit results recorded - [ ] Data-retention and residency choices approved - [ ] Production certification decision recorded ## Support request format When reporting an issue, provide the tenant environment, timestamp, request ID, model identifier, endpoint status, and a redacted description of the request. Do not include API keys, provider credentials, or sensitive prompt contents.