README.md

---
title: AKD - Code Search Agent
emoji: 💻
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
short_description: Agent that discovers public scientific code repositories.
---

# 💻 Code Search Agent

A chat demo of the **CARE v2 Scientific Code Discovery Agent**. Describe a
scientific task and the agent discovers relevant **public code repositories**
(NASA-verified repo search, the Science Discovery Engine, optional ASCL/ADS
citation evidence, and the web), then returns a ranked, evidence-backed
comparison. Each answer keeps a visible **agent-activity** timeline and a
collapsible **reasoning trace**, and you can keep chatting to refine the results.

**Artifacts-driven:** the agent's instructions are NOT hardcoded. They are loaded
at startup from the agent's CARE workspace artifacts bundled in `./artifact` — a
copy of [NASA-IMPACT/akd-plugins](https://github.com/NASA-IMPACT/akd-plugins)
→ `plugins/code-search-assistant` (the skill's `SKILL.md` is bundled as
`agents.md`; `references/` — per-domain contexts, guardrails, tool specs, output
spec — ride along and are exposed to the agent through a `read_reference` tool).

**Runtime:** pydantic-ai (OpenAI Responses API) + the plugin's hosted FastMCP
discovery servers + OpenAI hosted web search. **Bring your own OpenAI key** —
entered in the UI, used only for your session, never stored. The Space owner
supplies the MCP tokens (secrets).

**Guardrailed (pydantic-ai v2 harness):** every turn is checked by the
[NASA-IMPACT/akd-guardrails](https://github.com/NASA-IMPACT/akd-guardrails)
service, attached as `InputGuard` / `OutputGuard` capabilities on the agent —
`gliguard` (GLiNER) screens each user prompt *before the model is invoked*
(hard block, zero tokens), and `risk_agent` (LLM judge) reviews the final
answer (with the run's tool returns as grounding context) before it renders.
No guard logic lives in this app; it only relays verdicts. Blocked turns show
`⛔ Blocked by AKD input/output guardrails: <risks>`, and blocked answers never
enter the conversation memory. If the guardrails service itself is unreachable,
checks fail open (logged).

## Run locally

```bash
cd code-search-agent
pip install -r requirements.txt
# .env (not committed): CODE_SEARCH_MCP_KEY=… (+ optional vars below)
python app.py
```

## Deploy (private Docker Space)

See [DEPLOY.md](DEPLOY.md) for the full walkthrough. In short:

1. Create a **private** Space with **SDK: Docker**.
2. Set runtime secrets in **Settings → Secrets** (no build secrets needed —
   all dependencies are public):
   - `CODE_SEARCH_MCP_KEY` — FastMCP token for the primary discovery server.
   - optional: `CODE_SIGNALS_MCP_KEY`, `ADS_ASCL_MCP_KEY`.
3. Push `Dockerfile`, `app.py`, `requirements.txt`, `bot-avatar-v2.png`,
   `artifact/`, and this `README.md` to the Space.

The OpenAI key is supplied by each visitor at runtime (bring-your-own-key).

## Configuration (runtime env vars / Space secrets)

| Variable | Required | Purpose |
| --- | --- | --- |
| `CODE_SEARCH_MCP_KEY` | yes | Token for the primary discovery server (`repository_search_tool`, `sde_search_tool`). |
| `CODE_SEARCH_MCP_URL` | no | Override the primary server URL (default: the plugin's `sde-repo-search` server). |
| `CODE_SIGNALS_MCP_KEY` | no | Token for the code-signals server (static code inspection channel). |
| `CODE_SIGNALS_MCP_URL` | no | Override the code-signals server URL. |
| `ADS_ASCL_MCP_KEY` | no | Token for the ASCL/ADS server (Astrophysics citation channel). |
| `ADS_ASCL_MCP_URL` | no | Override the ASCL/ADS server URL. |
| `AKD_GUARDRAILS_URL` | no | AKD guardrails service base URL (default: the dev ALB). |
| `ARTIFACT_DIR` | no | Artifact folder override (default `./artifact`). |
| `AGENT_MODEL` | no | Default model id (default `gpt-5.2`). |

Servers are probed once at startup: a channel whose token is missing or rejected
is dropped and disclosed to the agent, which notes it in **Search Notes** instead
of fabricating results.