# External API Reference Implementation

## Decision

The source-grounded semantic explainer should have an external API-backed reference implementation path before enterprise porting.

```text
One assistant contract, multiple deployment targets.
```

The external reference path proves the Find, Explain, and Assess behavior contract with public or non-sensitive approved corpus material, a simple chat front end, and an approved external model API adapter. The enterprise Microsoft-native path remains the internal deployment lane, informed by the Microsoft-native pilot work and any approved Copilot Studio, Azure, or other Microsoft-native route.

The behavior contract is portable. Hosting, model provider, adapter implementation, and enterprise platform can vary.

This is an architecture and design note only. It does not create a runtime chat UI, call an external API, add credentials, configure Cloudflare, configure Supabase, deploy infrastructure, or integrate with enterprise workflows.

Core thesis:

```text
The model is the interpreter.
The corpus is the authority.
```

## Purpose

The external reference implementation should let the team prove source-grounded behavior quickly outside enterprise plumbing.

The proof should answer whether the approved package structure can support useful interpretation before the project waits on internal deployment decisions, Microsoft-native configuration, or enterprise workflow integration.

The proof should:

- use only public, non-sensitive, approved material
- preserve the same source-grounded assistant contract defined for the semantic explainer
- prove Find, Explain, and Assess behavior with citations and refusals
- keep provider and model choice behind an adapter boundary
- keep reader links stable enough to inform future public and internal reader orientation
- produce evidence that can inform a later Copilot Studio, Azure, or Microsoft-native internal implementation

It should not prove provider approval, enterprise approval, data-class approval, workflow approval, production readiness, security approval, legal approval, regulatory approval, or GxP fitness.

## Candidate MVP Architecture

```text
Static/public AICD package or local corpus snapshot
  -> package manifest, context-pack files, source maps, hashes
  -> lightweight retrieval or direct section selection
  -> external chat front end
  -> API-backed model adapter boundary
  -> approved external test adapter
  -> answer with citations, refusals, and reader links
```

Candidate external adapters may include:

- OpenAI API
- Z.ai or GLM-class compatible endpoint
- Gemini API
- another explicitly approved external testing adapter
- future local or open-weight adapter for public-corpus evaluation
- future Microsoft-native internal agent path

The architecture must not hardcode one premium model assumption. Find and Explain over a strongly cited approved corpus may be candidates for cheaper hosted models. Assess may require stronger reasoning when ambiguity, novelty, risk, or consequence warrants escalation. Open-weight, local, edge, or offline models may be evaluated later, but enterprise use remains gated by data classification, security, licensing, supplier-risk, model provenance, support posture, and approved hosting.

This issue documents the adapter posture. It does not implement adapter code, model routing, provider calls, benchmarks, or provider configuration.

## Minimum Viable Chat Front End Requirements

The first chat shell can be simple. It only needs enough interface behavior to exercise the assistant contract.

Minimum requirements:

| Requirement | Boundary |
|---|---|
| Mode selection | Preserve Find, Explain, and Assess as explicit modes. |
| Corpus visibility | Load or reference only the approved public corpus snapshot, context-pack files, source maps, artifact manifest, grounding rules, glossary, and public reader targets. |
| Source selection | Support lightweight section selection or direct context selection before a model call. Do not require vector search for the first proof. |
| Answer rendering | Show the answer, source citations, refusal state when applicable, and reader links where stable public targets exist. |
| Approval boundary | Preserve field-guidance-not-policy language and avoid implying tool, data, workflow, production, or enterprise approval. |
| Pulse-check separation | Keep external-web pulse checks visibly separate from Playbook-grounded answers. |
| Credential safety | Do not place provider API keys, secrets, tokens, or provider credentials in browser-visible code or static files. |

The front end itself is out of scope for this issue. Issue #159 should evaluate whether a static-site chat shell and serverless provider-proxy boundary are sufficient for implementation.

## API-Backed Model Adapter Boundary

The adapter boundary should isolate provider-specific details from the assistant contract.

The contract should provide a stable request shape:

- mode: Find, Explain, Assess, or explicit external pulse check
- user question or proposal text
- selected source snippets or source references
- citation map entries
- reader target links where available
- refusal rules
- routing hint or model-tier hint when later runtime work approves routing

The contract should require a stable response shape:

- answer text or refusal text
- cited source references
- reader links where available
- source-boundary statement
- generated-derivative label for assessment outputs
- optional uncertainty or missing-evidence fields
- optional cost, token, latency, or model-tier metadata when later runtime work approves collection

Provider adapters should be swappable. A provider-specific adapter may format prompts, map request fields, normalize responses, and surface refusal or error states, but it must not change the source-grounded behavior contract.

The server-side credential boundary belongs to the implementation-gate work in #159. This note only records that external model APIs require a non-browser secret boundary before any real provider call is made.

## Approved-Corpus Loading Strategy

The first proof should start with package structure rather than retrieval infrastructure.

Allowed external prototype corpus:

- public AICD Markdown files
- generated context-pack files
- `docs/artifact-manifest.json`
- product-architecture docs
- grounding rules
- glossary
- source maps
- public static HTML links as reader targets
- validation receipts when provenance or assessment depends on them and they are approved for public/non-sensitive use

Package-first source selection should use:

```text
approved corpus snapshot
  -> artifact manifest
  -> section ids
  -> source paths
  -> canonical titles
  -> context-pack files
  -> citation map
```

A lightweight local retrieval or section-selection layer may be described for a later runtime ticket. The first proof should not require a vector database, graph database, hosted retrieval service, durable memory, connector ingestion, private corpus ingestion, or database-backed state.

## Citation And Source-Boundary Behavior

Every Playbook-grounded answer should cite approved package material. The strongest available citation should include:

1. artifact ID and title
2. section ID and section title
3. source path
4. context-pack path or source-map reference
5. claim ID or source boundary when the answer depends on claim posture
6. public reader target link when a stable page or anchor exists

Reader links help people inspect the package. They do not replace source citations.

If a citation or reader target is unavailable, the assistant should state that limitation rather than inventing a reference.

Assessment outputs are generated derivatives. They may cite approved sources and proposal evidence, but they do not become canonical playbook source, approval records, validation receipts, or governance decisions.

## Refusal Behavior

Refusal is required product behavior, not a failure.

Use explicit refusal when:

- the approved package is silent
- the proposed answer would require model memory as authority
- the user asks for approval meaning the package cannot grant
- the submitted proposal lacks enough evidence for assessment
- the user asks to use private or sensitive material in the external proof
- external-web information is requested in Playbook-grounded mode

Required refusal patterns remain:

```text
Not found in the approved playbook package.
```

```text
The playbook provides guidance, but it does not approve this tool, data class, workflow, production use, or company policy.
```

```text
The submitted proposal lacks enough evidence to assess this criterion.
```

## External-Web Pulse-Check Boundary

External pulse-check mode is separate from Playbook-grounded answers.

```text
Use current external sources only when explicitly requested.
Label output as external context.
Do not overwrite or silently modify playbook guidance.
Do not treat external findings as approved corpus guidance.
```

External pulse checks may inform future issue creation, corpus review, or update candidates. They must not silently modify the playbook, override source boundaries, become approved guidance, or drive assessment findings without a clear external-context label.

If a future external pulse-check adapter uses web search or current external sources, that mode needs its own citation, source-quality, and provider-boundary rules. It is not the default Playbook-grounded mode.

## External Hosting And Support Infrastructure Options

The external proof should not assume GitHub Pages is the only hosting path.

| Option | Fit | Boundary |
|---|---|---|
| Cloudflare Pages plus Functions or Workers | Strong candidate for the external reader/chat shell because static hosting and provider-proxy boundary can live in one platform pattern. | This issue does not deploy Cloudflare, configure secrets, implement Workers, or approve production hosting. #159 should evaluate the implementation boundary. |
| GitHub Pages plus separate proxy | Viable when the existing static site remains the reader shell and a separate server-side boundary handles provider credentials. | Splits static hosting from API boundary. GitHub Pages alone must not hold provider keys or execute secret-backed API calls. |
| Local-only developer proxy | Useful for private technical testing with public corpus before hosted proof work. | Does not create a public proof path or enterprise deployment pattern by itself. |
| Azure Function or Azure-hosted internal app | Potential bridge toward Microsoft-native implementation when enterprise approval exists. | Enterprise use must remain governed by internal platform, data, security, and workflow approval. |
| Supabase-assisted support path | Optional support infrastructure for auth, object storage, proposal uploads, persistence, review records, logs, or corpus snapshots. | Not required for the first proof unless persistence, auth, upload handling, durable records, or database-backed state is explicitly needed. |

Supabase should remain optional support infrastructure for the first proof. It should not become required unless the design needs auth, object storage, proposal uploads, persistence, review records, logs, corpus snapshots, or database-backed state.

## Portability To Microsoft-Native Internal Deployment

The external proof should leave behind a portable behavior contract that can map to internal deployment targets.

| Contract element | External reference path | Microsoft-native internal path |
|---|---|---|
| Reader surface | Public static package, Cloudflare Pages candidate, or GitHub Pages plus reader targets. | Internal static site, Azure static endpoint, SharePoint-controlled document location where appropriate, or other approved internal reader surface. |
| Grounding corpus | Public/non-sensitive AICD package snapshot, context-pack files, source maps, and artifact manifest. | Approved internal corpus and context-pack files under enterprise data, security, and access-control rules. |
| Interpretation surface | Simple chat shell with external API-backed adapter boundary. | Copilot Studio, Azure-hosted internal app, Microsoft-native agent, or another approved internal route. |
| Model adapter | OpenAI, Z.ai or GLM-class compatible endpoint, Gemini, future local/open-weight adapter, or other approved external testing adapter. | Copilot Studio knowledge sources, Azure OpenAI, Microsoft-native orchestration, or another approved internal agent path. |
| Citation behavior | Cite package sources and link to public reader targets where available. | Cite approved internal package sources and link to stable internal reader targets where available. |
| Assessment output | Generated derivative with cited source basis and missing-evidence behavior. | Generated derivative subject to human reviewer authority and internal governance records. |

The external reference path complements the Microsoft-native internal pilot. It does not replace it, bypass it, or approve enterprise use.

## Security And Data Boundary For External Testing

External testing must use only public, non-sensitive, approved material.

Do not use:

- company-sensitive material
- private or confidential material
- regulated, GxP, PHI, PII, security-sensitive, or personal data
- enterprise-only documents
- unapproved proposal submissions
- private tickets, private comments, or internal review records
- credentials, keys, secrets, tokens, or browser-visible provider configuration

The external proof should be package-first and public-corpus-first. If testing requires persistence, auth, uploads, durable records, logs, corpus snapshots, or private corpus handling, that is a separate approved scope decision.

## Out Of Scope Until Explicitly Approved

This issue does not:

- build the chat front end
- implement static-site chat bolt-on behavior
- implement a serverless proxy
- call OpenAI, Z.ai, Gemini, or any external model API
- add API keys or credential handling
- add runtime provider or model execution
- add model routing code
- deploy to Cloudflare
- configure Cloudflare Pages, Functions, or Workers
- configure Supabase
- make Supabase required for MVP
- add auth, uploads, persistence, logs, review records, or corpus snapshots
- add vector database infrastructure
- add hosted retrieval service
- add graph database infrastructure
- add connector ingestion
- add durable memory
- use private or company-sensitive data externally
- replace the Microsoft-native internal pilot
- create enterprise workflow integration
- approve any provider, model, tool, data class, workflow, production use, policy posture, security posture, legal posture, regulatory posture, or GxP use case

## Relationship To Existing Issues

| Issue | Relationship |
|---|---|
| #153 | Builds on the source-grounded semantic explainer by preserving Find, Explain, Assess, citations, refusals, field-guidance-not-policy posture, and generated-derivative assessment boundaries. |
| #155 | Complements the Microsoft-native internal pilot by defining an external proof path before porting to Copilot Studio, Azure, or another approved internal route. |
| #158 | Incorporates workload-to-model routing discipline by avoiding a single premium model assumption and preserving future task-based routing without implementing it here. |
| #78 | Informs the assistant prototype by defining the external proof path and the portable behavior contract. |
| #79 | Keeps backend, graph, vector, hosted retrieval, connector ingestion, and durable-memory evaluation deferred until package-first testing proves need. |
| #88 | Should inform reader orientation because external and internal answers should link to stable reader targets when those targets exist. |
| #151 | Does not supersede DOCX rebuild idempotence, which remains separate deterministic artifact-generation hygiene. |
| #159 | Sets up the next implementation-gate issue for static-site chat shell and serverless API proxy requirements, including Cloudflare Pages/Workers and optional Supabase support. |