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:

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

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).