> For the complete documentation index, see [llms.txt](https://docs.arcv.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arcv.network/2.-contributor-and-annotator-guide/2.3-byo-key-copilot.md).

# 2.3 BYO-Key Copilot

The Worker AI Copilot Hub connects a contributor's chosen model endpoint to critique, rationale drafting, and answer correction. It is an advisory subsystem: generated text is evidence to inspect, not an autonomous vote, a verified test result, or authority to release escrow. The contributor remains responsible for the submitted judgment.

The current interface uses an inline collapsible drawer rather than a separate floating application. Model requests are real and may consume a paid API allowance even though workbench earnings are simulated. Assistance is optional; manual comparison and correction remain available without a connected model.

## Credential handling: the actual security boundary

**The present implementation does not provide memory-only or session-only credential storage.** After a successful connection test, it saves the provider, API key, endpoint, and model as JSON in browser `localStorage` under `arcv.worker-copilot.v1`. The stored key is not application-encrypted. A masked password field conceals its display; it does not encrypt storage.

`localStorage` persists across browser sessions and can be represented on persistent disk by the browser. It is therefore inaccurate to promise that keys never reach disk or disappear when a tab closes. The browser's persistence model is described in the [localStorage reference](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).

The inspected Copilot request path sends credentials and task text directly from the browser to the selected model endpoint. It does not route those requests through an ARCV API server, and its transport contains no credential-logging call. This is a specific statement about the implemented path, not a universal guarantee against extensions, injected scripts, developer tools, device compromise, custom gateways, or provider logging.

A genuine memory-only design would require changing the implementation, removing persistent writes and legacy saved values, and verifying the full lifecycle. Even memory-only storage would not guarantee that an operating system never pages process memory to disk. This documentation does not claim that such a migration has already occurred.

## Drawer architecture and connection lifecycle

```
Contributor enters configuration
             |
             v
Browser validates provider, endpoint, model and key presence
             |
             v
Quick Test & Save -> selected provider receives a test request
             |
        valid streamed completion
             |
             +--> active configuration in React memory
             |
             +--> unencrypted configuration in localStorage

Task assistance:
Prompt + A + B + selected response
             |
             v
Browser fetch -> configured provider / local model -> streamed text
             |
             v
Human inspection -> edited rationale or patch -> review acknowledgment

Disconnect / forget -> abort request + clear memory + remove saved entry
```

On refresh, the drawer loads saved settings but does not silently reconnect or send a prompt. **Quick Test & Save** must succeed again before the active connection is established. If browser storage is unavailable after a successful test, the connection can remain active for the session and the interface reports that it could not save the key.

Editing draft settings does not replace an already active connection until another test succeeds. Inspect the active provider/model pill before sending task text, particularly after changing an endpoint. Changing providers clears the draft key and restores the new provider's default endpoint and model.

## Provider transports and model selection

| Provider          | API base                            | Current preset and requested alternatives                                                                            |
| ----------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| OpenAI            | `https://api.openai.com/v1`         | Default `gpt-4o-mini`; choose **custom** for `gpt-4o` if available to the account and compatible with this transport |
| Anthropic         | `https://api.anthropic.com/v1`      | Legacy preset `claude-3-5-sonnet`; replace with an exact supported Claude API model ID                               |
| Groq              | `https://api.groq.com/openai/v1`    | Legacy default `llama-3.1-70b`; **custom** accepts `llama-3.3-70b-versatile` when permitted                          |
| Local Ollama/vLLM | `http://localhost:11434` by default | Use the exact model identifier served by the running local endpoint                                                  |

Provider integration means a compatible request transport exists. It does not guarantee that every preset names an available model. Anthropic's model lifecycle documentation identifies retired Claude 3.5 Sonnet versions; the bare UI label must not be treated as a supported deployment identifier. Consult the [Claude lifecycle reference](https://platform.claude.com/docs/en/about-claude/model-deprecations). Groq documents [`llama-3.3-70b-versatile`](https://console.groq.com/docs/model/llama-3.3-70b-versatile), but account permissions and service availability still govern requests.

The client sends text messages with streaming enabled and requests up to 1,800 output tokens. It does not implement every provider's tool, image, audio, reasoning, or response API. A model requiring another request shape can fail even when its identifier is syntactically accepted. Local compatibility likewise depends on the server's supported API; see [Ollama's compatibility documentation](https://docs.ollama.com/api/openai-compatibility).

## Connecting a provider

1. Open **Connect AI Copilot (BYO Key)** from the workbench.
2. Select a provider and verify the resulting API base URL.
3. Enter a dedicated provider API key in the masked field. Local endpoints may omit a key when their server configuration permits it.
4. Choose a compatible preset or **custom** and enter the precise model identifier.
5. Confirm that the campaign permits sending its task material to this destination.
6. Select **Quick Test & Save**. The test requests an `OK` response without task data and can incur a provider charge.
7. Inspect the resulting active pill and status message before requesting assistance.

A successful test establishes request and stream compatibility, not factual reliability, zero retention, or authorization to disclose enterprise material. The test accepts a completed response; it is not an independent audit of the model's identity or capability.

Prefer credentials with limited scope and spend limits where the provider supports them. Do not enter wallet seed phrases, signing keys, or unrelated infrastructure secrets. The Copilot API key authorizes model usage; it does not connect an EVM wallet or grant permission to settle a bounty.

## Endpoint and transport specifications

OpenAI-compatible requests use `/chat/completions` and a bearer authorization header when a key is present. Anthropic uses `/messages`, its API-key and version headers, and a direct-browser-access header. Local endpoints receive a `/v1` suffix if absent before the completion path is added. Supply an API base, not a full completion URL.

Validation permits HTTPS and allows HTTP only for loopback hosts. It rejects embedded URL credentials, query strings, and fragments. However, this is not an official-provider allowlist: a valid custom HTTPS endpoint can receive the key. Inspect the hostname before saving, and never treat HTTPS alone as proof that a destination belongs to the selected provider.

Requests omit cookies, suppress the referrer, reject redirects, request no HTTP caching, and support cancellation. Those controls reduce specific exposure paths; they do not prevent a destination server from recording what it receives. The browser's `no-store` request option is not a provider data-retention contract.

Responses must be server-sent event streams. The parser reads incremental text deltas, handles event boundaries, and requires a recognized completion marker. It rejects malformed, empty, interrupted, or oversized output instead of presenting a partial response as completed. The implementation caps accumulated text at 24,000 characters and an unprocessed event buffer at 100,000 characters; these are defensive client limits, not provider context-window specifications.

A request has a 60-second timeout. Only one request runs at a time. Task, response selection, workspace mode, and patch-state changes cancel active generation to avoid applying a stale suggestion to a changed evaluation. Cancellation stops the local stream but cannot guarantee the provider has not already processed or billed the request.

## Using assistance without outsourcing judgment

### AI Diff Assist

The critique request sends the prompt, both candidates, and selected-response identifier. With an active model it streams comparative analysis; without one, the interface shows demonstration analysis. Neither output is an independent production validator decision.

Ask whether the analysis identifies a concrete defect and whether that defect is present. In the Fibonacci task, a useful observation concerns repeated recursive calls. A claim that one candidate uniquely rejects negatives is false because both do. Check the text against the source rather than accepting the assistant's preferred answer.

### Draft rationale

The rationale helper requests two sentences evaluating the selected answer against the alternative and instructs the model to acknowledge a weaker selection honestly. A completed draft replaces the rationale field, is limited to 4,000 characters, and activates a human-review requirement.

The request does not include the current rating grid or a separate enterprise rubric document. Do not assume the model evaluated requirements absent from the supplied task context. Preserve existing manual wording before requesting a replacement draft.

Edit the draft to remove unsupported evidence and align it with the actual rubric. Do not retain “tests passed,” “sources confirmed,” or measured speed claims unless you performed those checks. The selected answer is context, not an instruction for the assistant to rationalize an error.

### Auto-Suggest Patch

Select a starting response before opening correction assistance. The patch request asks for corrected Python code, edge-case handling, and type hints. Returned outer code fences are removed and the result is limited to 20,000 characters before entering the editor. These transformations do not validate syntax or correctness.

The current editor contents are not sent as a revision target. A completed suggestion replaces them, so preserve any manual correction you want to retain before generating another patch.

Inspect the entire result. Check that function names, allowed dependencies, output behavior, and input assumptions still match the assignment. A generated patch can introduce a new bug while fixing the original one. Explicitly review it before submission; the acknowledgment is a human action, not proof of a successful test suite.

### Source checking, code analysis, and schemas

The current Copilot supplies text generation, not a built-in browser, execution sandbox, or JSON Schema validator. It can suggest a source to inspect, reason about a boundary case, or identify a likely schema defect. It cannot establish that a page was fetched or code executed simply by saying so.

For factual work, inspect the primary source separately and verify that it supports the exact claim. For code, use an authorized isolated test environment if execution is required; do not execute untrusted task code on a credential-bearing workstation merely to satisfy a suggestion. For schemas, distinguish syntactically valid JSON from compliance with a declared schema dialect and validate with an appropriate tool when required.

## Privacy boundaries and removal procedure

| Boundary            | Implemented behavior                            | Remaining exposure                                                                      |
| ------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| ARCV request server | No Copilot proxy in the inspected path          | Other application paths and infrastructure require independent assessment               |
| Browser storage     | Plain configuration saved locally after testing | Same-origin scripts and compromised browser/device access can expose it                 |
| Model destination   | Receives key and submitted task text            | Provider or custom gateway can retain data under its own policy                         |
| Local model         | Request can stay on loopback                    | Local server logs, model behavior, and network configuration remain operator-controlled |
| User interface      | Password masking                                | Does not encrypt the value or prevent script access                                     |

Use the drawer's disconnect/forget control when finished. It cancels active requests, clears in-memory configuration, and removes the saved storage entry. If removal fails, the interface directs you to clear the site's browser data. Closing the drawer or tab is not equivalent to forgetting the key.

Removing browser data does not revoke the provider credential or delete provider-side records. Revoke or rotate a credential at its issuer if exposure is suspected. Local mode avoids a cloud request only when the configured server actually runs locally and does not relay elsewhere; the provider label alone cannot establish that property.

## Troubleshooting

| Result                               | Interpretation and corrective action                                                                    |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Authentication or permission failure | Check key validity, provider, and model permissions; do not paste credentials into task text            |
| Rate limit or quota failure          | Check provider allowance and retry policy rather than repeatedly resubmitting                           |
| Invalid endpoint or model            | Use an API base and a supported exact model ID                                                          |
| Network / CORS failure               | Confirm the server is reachable and permits the application's origin                                    |
| Local endpoint unavailable           | Start the local server and verify its port, model, and browser access permissions                       |
| Interrupted or malformed stream      | Retry only after checking endpoint compatibility; incomplete text is not accepted as a successful draft |
| Saved settings but inactive status   | Run the test again after refresh; automatic reconnection is intentionally absent                        |

For local servers, allow the specific trusted application origin and retain appropriate access controls. Do not disable browser security or expose an unauthenticated model endpoint broadly as a shortcut around CORS. Review [Rubrics and Golden Patch](/2.-contributor-and-annotator-guide/2.2-rubrics-and-golden-patch.md) before promoting generated text into a submitted contribution.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.arcv.network/2.-contributor-and-annotator-guide/2.3-byo-key-copilot.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.