DEPLOY.md

# Deploying to a private Hugging Face Docker Space

The app is fully self-contained: **public PyPI dependencies only** (pydantic-ai,
gradio) and the agent's CARE workspace artifacts bundled under `artifact/`.
No build secrets, no private packages — pushing is just git.

## 0. Prerequisites

- A Hugging Face account (and the `huggingface_hub` CLI: `pip install -U huggingface_hub`).
- The **FastMCP token(s)** for the discovery servers (see Secrets below). At
  minimum `CODE_SEARCH_MCP_KEY`; the token must be valid for the server URL the
  Space uses (`CODE_SEARCH_MCP_URL` can override the default).

## 1. Create the Space

UI: huggingface.co → **New Space** → SDK **Docker**, **Private**, name e.g.
`code-search-agent`.

Or CLI:

```bash
huggingface-cli login        # paste an HF token (write)
huggingface-cli repo create code-search-agent --type space --space_sdk docker --private
```

## 2. Set the secrets (Space → Settings → Secrets)

All secrets are **runtime** — there is no build secret anymore.

| Name | Required | Value |
| --- | --- | --- |
| `CODE_SEARCH_MCP_KEY` | yes | FastMCP token for the primary discovery server (`repository_search_tool` + `sde_search_tool`). |
| `CODE_SEARCH_MCP_URL` | no | Primary server URL override (default: the plugin's `sde-repo-search` server; set this if your token belongs to a different deployment). |
| `CODE_SIGNALS_MCP_KEY` | no | Token for the code-signals server (static code inspection). |
| `ADS_ASCL_MCP_KEY` | no | Token for the ASCL/ADS server (Astrophysics citation channel, Step 5). |
| `AKD_GUARDRAILS_URL` | no | AKD guardrails service base URL (default: the dev ALB; gliguard input + risk_agent output checks relay here). |

The OpenAI key is **not** a secret — each visitor enters their own in the UI.

At startup the app probes each configured server, drops any that fail auth (so a
bad token can't break every chat turn), and tells the agent which channels are
live; the agent notes missing channels in **Search Notes** instead of fabricating.

## 3. Push the files

```bash
git clone https://huggingface.co/spaces/nasa-impact/code-search-agent
cd code-search-agent
git add Dockerfile app.py requirements.txt README.md bot-avatar-v2.png artifact
git commit -m "Code search agent v2 — artifacts-driven pydantic-ai backend"
git push
```

(`.env` and `.venv/` are for local runs only and are gitignored.)

## 4. Build & test

HF builds automatically on push (the build is light — public wheels only, a
couple of minutes). When it's **Running**, open the Space, paste your OpenAI
key, and run a search. The boot log prints one `[mcp] <server>: [tools…]` line
per live discovery server — check it if a channel seems missing.

## Updating the agent's instructions

The prompt and references live in `artifact/` — a copy of
`NASA-IMPACT/akd-plugins` → `plugins/code-search-assistant/skills/code-search`
(`SKILL.md` → `artifact/agents.md`, `references/*` → `artifact/*`). To pick up a
new revision of the plugin, re-copy those files and push; `app.py` needs no
changes.

## Troubleshooting

- **"No discovery MCP server is configured"** in chat → `CODE_SEARCH_MCP_KEY`
  is missing, or every configured server failed auth (see the boot log).
- **A channel is missing from results** (e.g. no ASCL/ADS evidence) → that
  server's token isn't set or was rejected; the agent will say so in Search
  Notes. Set/fix the corresponding secret.
- **401 in chat replies** → the *visitor's OpenAI key* was rejected; that's
  theirs to fix (the MCP tokens are unrelated to this error).