README.md

metadata

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 → 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 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

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