# QNE AI Provider Relay Doctrine V1

Date: 2026-06-11

Status: current planning doctrine

Layer: Layer B current support doctrine under the main node view-session doctrine

Scope: QNE AI provider capability, OpenAI relay skill, qne-p2p transport, token accounting, scalable relay deployment, and future provider-operated QNE nodes.

## Purpose

QNE users should be able to use AI during onboarding and later node operation without every user needing a separate OpenAI account or API key.

The first implementation is a QNE node running an AI relay skill. The relay skill holds the provider API key in its node secrets, receives AI requests from Home Nodes over qne-p2p, calls the provider API, and returns the model response and token usage to the requesting Home Node.

The relay exists only to provide shared provider API access. It is not the user's account authority, conversation owner, or billing ledger.

## Architecture

The relay is a `QNENodeSkill`, not base node logic.

```text
Home Node --qne-p2p--> QNE Relay Node + QNEOpenAIRelaySkill --OpenAI API--> OpenAI
```

The relay skill implements the standard QNE AI provider capability. To the Home Node, a relay and a future provider-operated QNE node should look like the same class of peer.

```text
Home Node --qne-p2p--> AI Provider Capability
```

This avoids tech debt: the initial relay is just the first provider-node implementation.

## Transport Rule

AI relay traffic starts on qne-p2p. HTTP is not the first-stage protocol for Home Node to relay communication.

The reasons are:

- QNE identity and authorization already belong in qne-p2p.
- The relay should authenticate QNE nodes as peers, not as web users.
- The same protocol must work for local, cloud, and future provider-operated nodes.
- Avoiding an HTTP bridge avoids a later migration step.

The relay may use HTTPS internally to call OpenAI because that is the provider API transport.

## Provider Capability Contract

A QNE AI provider capability accepts structured requests and returns structured responses.

Request fields should include:

```text
request_id
source_home_node_id
source_user_uuid
conversation_id
purpose
requested_model_class
messages or prompt
context summary or context references
max_tokens or cost class
streaming preference
```

Response fields should include:

```text
request_id
provider_node_id
model_used
response content or stream events
input_tokens
output_tokens
total_tokens
status
provider_response_id if available
```

The Home Node owns conversation state and persists the returned usage.

## Token Accounting Doctrine

The relay does not need to keep a permanent ledger.

The Home Node is trusted QNE software and records its own token tally in persist. The user normally has no supported path to change the token tally without breaking trust in their own node state.

The relay returns usage data for each request. The Home Node stores it locally and uses it later for fair contribution, subscription, or token-cost reimbursement.

The relay may keep short-lived operational counters for safety:

- requests per Home Node per minute
- concurrent requests per Home Node
- estimated tokens per Home Node per day
- expensive-model calls per Home Node per day
- provider error and retry state

These counters are not a billing ledger. They exist to protect the relay API key and prevent runaway costs.

## Cost Doctrine

QNE may add a small margin to provider token costs.

The margin can pay for:

- relay cloud instances
- bandwidth and operations
- failed payments or free trials
- reserve capacity
- future community-operated relay rewards

The infrastructure margin should be small compared with model token cost. The main cost driver is provider usage, not Hetzner compute.

## Scaling Doctrine

Relay nodes are horizontally scalable.

To add capacity:

1. Start another QNE node.
2. Enable the AI relay skill.
3. Add provider API credentials to that node's protected secrets.
4. Register or advertise the node as a QNE AI provider.
5. Let Home Nodes select from available trusted providers.

Relays should be replaceable and mostly stateless. If one relay fails, a Home Node can retry another trusted relay.

The relay selection system should eventually consider:

- trust level
- geographic latency
- model classes supported
- current availability
- cost margin
- per-node quotas
- provider health

## Future Provider-Operated QNE Nodes

The preferred future architecture is for AI providers, including OpenAI if they choose, to run one or more QNE provider nodes directly.

```text
Home Node --qne-p2p--> OpenAI QNE Provider Node
```

In that model QNE does not need to hold a shared provider API key for those requests. The provider node handles its own authorization, limits, billing, and model execution.

The first QNE OpenAI relay must therefore be implemented as an adapter behind the same QNE AI provider capability. It should not create a special one-off Home Node integration.

## Model Policy

Home Nodes request a model class, not a hardcoded provider model string.

Examples:

```text
onboarding
pa_standard
code_help
high_reasoning
low_cost_summary
```

The relay maps these classes to configured provider model names. This allows model upgrades without changing Home Node code.

Higher-cost model classes should be controlled by Home Node policy, relay policy, or explicit user approval depending on maturity.

## Early Implementation Boundary

The first implementation should be deliberately small:

- qne-p2p only between Home Node and relay
- relay implemented as `QNENodeSkill`
- OpenAI API key stored only in relay node secrets
- no relay permanent ledger
- Home Node persists token usage
- simple model-class mapping
- simple per-node safety limits
- no payment enforcement in first pass

The relay should be suitable for many small cloud instances or larger Hetzner instances, adjusted by quantity and performance as demand grows.
